内容
# windows-gui-mcp
[](https://github.com/dcl632/windows-gui-mcp/actions/workflows/ci.yml)
[](https://pypi.org/project/windows-gui-mcp/)
[](https://github.com/dcl632/windows-gui-mcp/releases)
[](LICENSE)
用于 AI 编程代理的 Windows GUI 自动化 MCP 服务器。
`windows-gui-mcp` 帮助代理通过语义 UI 自动化而不是脆弱的坐标点击来操作 Windows 桌面应用程序。它设计用于需要检查实时 Windows UI、操作稳定标识、验证每个操作并将成功的会话转换为可重用的脚本的代理工作流。
从 PyPI 安装：
```powershell
py -3.12 -m pip install "windows-gui-mcp[windows,ocr]"
```
演示和项目说明：
- [记事本和计算器演示](docs/demo.md)
- [示例工作流](examples/notepad_calculator.md)
- [路线图](docs/roadmap.md)
- [竞争定位](docs/competitive-positioning.md)
## 为什么存在该项目
AI 代理可以可靠地处理网页，因为浏览器公开了结构化的 DOM 状态。Windows 桌面应用程序更难处理：可见的 UI 通常是有状态的、异步的，并且容易因原始坐标而损坏。
该项目针对代理生态系统中的一个空白点：通过 MCP 实现对仅限 Windows 的桌面软件的可靠控制，以 UI 自动化作为默认接口，OCR/图像匹配作为显式回退。
该项目公开了一组小型 MCP 工具，使代理处于更安全的循环中：
1. 发现可见的窗口。
2. 聚焦目标窗口。
3. 转储 UI 自动化树。
4. 通过稳定标识查找控件。
5. 执行操作后进行验证。
6. 在语义查找失败后仅使用 OCR 或图像回退。
7. 从跟踪中生成 pywinauto 重放脚本。
## 工具模型
```text
AI 编程代理
|
| MCP stdio
v
windows_gui_mcp.server
|
v
tools/dispatch + 跟踪记录器
|
+-- 窗口 / 元素 / 输入 / 验证 / 等待
+-- 截图 / OCR / 回退 / 跟踪到脚本
|
v
Windows 后端阶梯
|
+-- pywinauto UIA 首选
+-- pywinauto win32 旧版回退
+-- pyautogui 图像/坐标 最后手段
```
## MCP 工具
| 工具 | 目的 |
| --- | --- |
| `list_windows` | 枚举可见的顶级窗口。 |
| `focus_window` | 将标题匹配的窗口带到前台并验证焦点。 |
| `dump_ui_tree` | 转储 UIA 树，以便代理可以选择稳定的标识符。 |
| `find_element` | 通过 `automation_id`、`name`、`control_type` 或 `class_name` 定位控件。 |
| `click_element` | 点击语义识别的控件并验证后置条件。 |
| `type_text` | 在目标控件中输入文本并可选地验证值。 |
| `hotkey` | 发送 pywinauto 样式的按键组合，例如 `^s` 或 `%{F4}`。 |
| `screenshot` | 捕获屏幕、窗口或区域。 |
| `wait_until_element` | 等待控件存在、可见或启用。 |
| `verify_text_exists` | 首先通过 UIA 验证文本，仅在请求时使用 OCR。 |
| `fallback_click_by_image_or_ocr` | 作为最后的手段，通过图像模板或 OCR 锚点点击。 |
| `generate_stable_script_from_trace` | 将当前跟踪转换为 pywinauto 重放脚本。 |
## 安装
需要 Python 3.12 或更新版本。
macOS 和 Linux 控制器机器可能附带较旧的系统 Python。如果 `python3 --version` 版本低于 3.12，请在运行 `pip install windows-gui-mcp` 之前安装 Python 3.12 或更新版本。实时 GUI 自动化仍然需要 MCP 服务器在拥有目标 UI 的 Windows 桌面会话上运行。
对于正常的 Windows 代理使用：
```powershell
py -3.12 -m venv .venv
.\.venv\Scripts\python -m pip install --upgrade pip
.\.venv\Scripts\python -m pip install "windows-gui-mcp[windows,ocr]"
```
从此存储库进行本地开发：
```bash
python -m venv .venv
./.venv/bin/python -m pip install --upgrade pip
./.venv/bin/python -m pip install -e ".[dev]"
```
在 Windows 上，当您需要实时 GUI 控制时，请安装可选的运行时额外功能：
```powershell
.\.venv\Scripts\python -m pip install -e ".[dev,windows,ocr]"
```
OCR 支持是可选的。如果您使用 Tesseract OCR，请单独安装 Windows 包，并确保 `tesseract.exe` 在 `PATH` 中。
## 运行
在拥有桌面会话的 Windows 机器上启动 MCP 服务器：
```powershell
windows-gui-mcp
```
在不启动 MCP stdio 传输的情况下检查 CLI 元数据：
```powershell
windows-gui-mcp --help
windows-gui-mcp --version
```
示例本地 MCP 客户端配置：
```json
{
"mcpServers": {
"windows-gui": {
"command": "windows-gui-mcp"
}
}
}
```
来自另一台机器的基于 SSH 的示例配置：
```json
{
"mcpServers": {
"windows-gui": {
"command": "ssh",
"args": [
"user@windows-host",
"C:\\path\\to\\windows-gui-mcp\\.venv\\Scripts\\windows-gui-mcp.exe"
]
}
}
}
```
## 示例工作流
这是记事本或计算器任务的预期代理循环：
```text
1. list_windows()
2. focus_window(title_regex="Notepad|Calculator")
3. dump_ui_tree(window_handle=...)
4. find_element(spec={"name": "Save", "control_type": "Button"})
5. click_element(
spec={"name": "Save", "control_type": "Button"},
expect_element_after={"class_name": "#32770"}
)
6. type_text(
spec={"automation_id": "1001"},
text="agent-notes.txt",
verify_value_contains="agent-notes.txt"
)
7. hotkey("%{ENTER}")
8. generate_stable_script_from_trace()
```
有关更详细的演练，请参见 [examples/notepad_calculator.md](examples/notepad_calculator.md)。
有关完整的转录、预期输出和生成的重放脚本形状，请参见 [docs/demo.md](docs/demo.md)。
## 安全规则
- 优先使用 `automation_id`，然后是 `name`，然后是 `control_type`，然后是 `class_name`。
- 不要从屏幕坐标开始。
- 通过具体的后置条件验证每个点击或文本输入。
- 在验证失败后重新转储 UI 树，而不是盲目重试。
- 将 OCR 和图像匹配视为回退，而不是主要的自动化路径。
## 开发检查
```bash
python -m compileall -q src tests
python -m pytest -q
ruff check .
python -m build
twine check dist/*
```
## 贡献和安全
有关开发工作流和自动化设计规则，请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。有关漏洞报告和桌面自动化安全期望，请参见 [SECURITY.md](SECURITY.md)。
## 许可证
MIT
