Windows-Use MCP Server

windows-use 的 MCP 封装 —— 把 Windows-Use Agent 的 全部底层工具（以及可选的整包 Agent 模式）暴露给任意 MCP 客户端 （ZCode / Claude Desktop / Cursor / Gemini CLI 等）。

• 通过辅助功能树（UI Automation）读取屏幕内容，不需要视觉模型，比截图识别更快更准

• 可以操作后台窗口（不抢焦点）

• 纯工具集模式（默认）不需要任何模型 API key —— 客户端里的模型直接驱动这些工具

⚠️ 安全警告：本服务能操控整个桌面、运行 PowerShell、读写文件，可造成不可逆更改。 建议在虚拟机 / Windows Sandbox 中部署，或仅在你信任的任务中使用。

与上游 / 官方 MCP 的关系

• Jeomon/Windows-Use：上游项目， 一个自带 LLM 决策循环的 Windows GUI Agent。本项目把它解包成纯工具集， 这样工具由你自己的客户端模型直接驱动，不再内置一层 Agent。

• CursorTouch/Windows-MCP：同一作者（CursorTouch） 的官方 MCP server（9k+ stars），只有工具层。

• 本项目的差异点：默认提供 Windows-Use 风格的纯工具集（含 wu_memory 持久记忆、 wu_file 文件操作），并且可以开启 wu_run_task 整包 Agent 模式—— 一个 server 同时拿到"工具层 + Agent 层"两种用法。

Related MCP server: Deskhand-mcp

特性

• 纯工具集模式（默认）：16 个工具直接调用 windows-use 底层函数，零模型依赖

• Agent 模式（可选）：设置 WINDOWS_USE_MCP_ENABLE_AGENT=1 后额外注册 wu_run_task， 把自然语言任务交给 windows-use 内置 Agent 完整执行（此时才需要 LLM API key）

• 支持虚拟桌面、持久记忆、网页抓取、文件操作

工具清单

在 MCP 客户端里工具名形如 mcp__windows-use__wu_xxx。

观察类（先调用这些了解环境）

操作类

Agent 模式（可选）

安装

要求：Windows 10/11，Python 3.10+

git clone https://github.com/kultur-512/windows-use-mcp.git windows-use-mcp
cd windows-use-mcp
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt

注：requirements.txt 把 mistralai 固定到 <2，因为 windows-use 0.8.1 与 mistralai 3.x 不兼容 （cannot import name 'Mistral'）。

配置到 MCP 客户端

ZCode（~/.zcode/cli/config.json）

{
  "mcp": {
    "servers": {
      "windows-use": {
        "type": "stdio",
        "command": "C:\\path\\to\\windows-use-mcp\\.venv\\Scripts\\python.exe",
        "args": ["C:\\path\\to\\windows-use-mcp\\server.py"],
        "timeoutMs": 60000
      }
    }
  }
}

Claude Desktop / 其他客户端（.mcp.json 或 claude_desktop_config.json）

{
  "mcpServers": {
    "windows-use": {
      "command": "C:\\path\\to\\windows-use-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\windows-use-mcp\\server.py"]
    }
  }
}

启动较慢（首次要生成 comtypes 类型库，1-2 秒），建议把超时调大到 60s。

开启 Agent 模式（可选）

"env": {
  "WINDOWS_USE_MCP_ENABLE_AGENT": "1",
  "WINDOWS_USE_MCP_PROVIDER": "anthropic",
  "WINDOWS_USE_MCP_API_KEY": "sk-...",
  "WINDOWS_USE_MCP_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
  "WINDOWS_USE_MCP_MODEL": "glm-5.3"
}

provider 支持 anthropic（含兼容接口）/ openai / litellm。

典型使用流程

让客户端模型这样工作：

1. wu_get_state —— 看当前有哪些窗口

2. wu_app switch 到目标窗口（或 launch 启动应用）

3. wu_get_elements —— 拿目标元素坐标

4. wu_click / wu_type 操作

5. 需要视觉确认时 wu_screenshot annotate=true

示例任务："打开记事本写一首关于 Windows 的诗并保存"：

1. wu_app(mode="launch", name="Notepad")
2. wu_wait(duration=2)
3. wu_get_elements()            # 找到编辑器区域坐标
4. wu_type(loc=[...], text="Windows 的诗……")
5. wu_shortcut(shortcut="ctrl+s")
6. wu_get_elements()            # 找到保存对话框
7. wu_type(loc=[...], text="poem.txt", press_enter=true)

Agent 模式可以一步到位：wu_run_task(task="打开记事本写一首关于 Windows 的诗并保存到 poem.txt")

自测

# 端到端测试 1：列出工具 + 调用观察工具
python test_client.py

# 端到端测试 2：操作工具（PowerShell/截图/应用列表）
python test_client2.py

排障

• 工具返回 thought:Field required —— 旧版 windows-use 要求每个工具调用带 thought 字段， server 已自动注入，升级到最新代码即可。

• MCP 显示 failed / 超时 —— 首次启动需生成 comtypes 类型库，把 timeoutMs 调到 60000； 仍失败则用配置里的 command + args 手动在终端跑一遍看报错。

• cannot import name 'Mistral' from 'mistralai' —— 执行 pip install "mistralai>=1.9.11,<2"。

• 元素树为空 / 窗口找不到 —— 先用 wu_app switch 把目标窗口带到前台，再 wu_get_elements。

License

MIT。上游 windows-use 同为 MIT， 使用/分发时请保留上游版权声明。