Windows-MCP —— 让任意 LLM 操控 Windows 桌面的 MCP Server

调研日期：2026-10-01 | 数据均为当日实测（GitHub API / PyPI / 源码）
本篇是《LLM 操控电脑浏览器.md》（abbrlink 6736）3.2 节「计算机/桌面控制 MCP」类目第一名的独立详细调研。
定位补充：本机已有 mcp-chrome / BrowserSkill 管浏览器，Windows-MCP 管整个桌面，互补不冲突。

1. 背景简介

一句话定位：让 AI Agent（任意 LLM）直接操控 Windows 操作系统的 MCP Server——文件导航、应用控制、UI 交互、QA 测试。
仓库：CursorTouch/Windows-MCP，MIT 协议，Python 编写（FastMCP 框架）。
作者：CursorTouch 开源组织，背后是个体开发者 Jeomon George（jeogeoalukka@gmail.com）。系列作品：Android-MCP（875★）、MacOS-MCP（188★），Windows 这款是旗舰。
创建：2025-05-13；最新版 v0.8.7（2026-09-30 发版，日更活跃），开发状态 Beta。
核心技术路线：UIA 无障碍树（a11y tree），底层 uiautomation/comtypes/pywin32——LLM 按”元素名”操作，不依赖截图视觉、不依赖特定模型，任何 LLM 都能用，vision 可选。
生产验证：README 宣称 Claude Desktop 扩展目录 2M+ 用户；上过 Trendshift 趋势榜；已进 MCP Registry 和 PyPI。
支持系统：Windows 7～11（实测 pyproject 要求 Python ≥ 3.14，README 徽章写 3.13+ 已过时）。

2. 怎么用 / 依赖 / 配置 / 上手难度

上手难度：低。核心就一行命令，前提是 Python 3.14+ 和 uv 包管理器。

# 前台运行（stdio 默认，给 Claude Desktop/Cursor 等直连）
uvx windows-mcp serve

# HTTP 传输（远程/共享访问）
uvx windows-mcp serve --transport streamable-http --host 127.0.0.1 --port 8000

# 注册成登录自启的每用户计划任务（详见第 8 节全局方案）
windows-mcp install
windows-mcp uninstall

官方给了十几种客户端现成配置：Claude Desktop、Claude Code、Codex CLI、Gemini CLI、Qwen Code、Perplexity Desktop、Autohand Code 等。
工具裁剪：--tools "Screenshot,Click,Snapshot" 只开指定工具，--exclude-tools "PowerShell,Registry" 屏蔽高危工具。
坑：① Windows 首选语言需为英文，否则 App-Tool（按开始菜单名启动应用）会失灵，非英文系统建议关掉该工具；② 首次安装拉依赖要 1~~2 分钟，首跑可能超时，忽略后重启即可；③ 配置文件放 `~~/.windows-mcp/config.toml`（CLI 参数优先）。

3. 对我的价值

多端 Agent 桌面操控通道：zcode / Hermes / dsh / WorkBuddy 全部可以通过一个共享实例获得 Windows 桌面原生操控能力（方案见第 8 节），补齐”浏览器之外的 Windows 应用自动化”这块。
与现有方案路线互补：Hermes computer_use 走 cua-driver（UIA+SendInput，偏视觉），Windows-MCP 是纯 a11y 树路线——按元素名点击、token 省、非视觉模型可用；mcp-chrome / BrowserSkill 管浏览器标签页，Windows-MCP 管桌面应用窗口，三件套拼齐。
爬虫/逆向辅助：Scrape（带 SSRF 防护）、DOM 模式抓网页元素、PowerShell / Registry / Process 工具做环境侦查与系统信息收集，一条 MCP 全带。
QA 自动化：Snapshot（交互元素 id）+ WaitFor（轮询 UI 状态）+ 截图，适合做 Windows 客户端软件的回归测试。

4. 能力边界

✅ 能做什么

UI 操控：Click / Type / Scroll / Move（含拖拽）/ Shortcut / MultiSelect / MultiEdit，全部支持按 UIA 元素标签定位（也支持坐标兜底）。
桌面状态感知：Screenshot（快照优先、支持区域/多显示器、降采样省 token）、Snapshot（完整 a11y 树 + 可选视觉）、WaitFor（单次调用内轮询等元素/窗口/文本）、DisplayInventory（显示器布局与 DPI）。
系统级工具：App（启动/切窗/缩放）、PowerShell、FileSystem（读写复制移动搜索）、Process（列进程/杀进程）、Registry（注册表增删改查）、Clipboard、Notification（toast 通知）。
浏览器：Snapshot use_dom=True 的 DOM 模式抓网页内容（Chrome/Edge/Firefox，Firefox 走 IAccessible2 兜底）。
远程访问全家桶：SSE / streamable-http、Bearer auth、IP 白名单、TLS、OAuth2+PKCE、CORS 白名单（默认关）、DNS rebinding 防护、Scrape SSRF 防护。

❌ 不能做什么

段落内精确选中一段文字（a11y 树限制，官方标注开发中）。
在 IDE 里写代码——Type 工具是整块打字，不是逐字符编辑。
玩游戏（游戏走 GPU 渲染/DirectInput，UIA 够不着）。

⚠️ 注意事项（官方 SECURITY.md 实锤）

非沙箱，全用户权限：每个工具调用都是真实系统操作，无预览、无撤销。官方工具风险分级：

风险	工具	说明
Critical	PowerShell	任意命令执行（官方表里叫 Shell）
High	Click / Type(clear=True) / Move 拖拽 / Shortcut	误点删除确认、覆盖文本、Alt+F4 等
Medium	App	启动应用但不改数据
Low	Snapshot / Wait / Scrape	只读（Scrape 会暴露浏览行为）

注：Registry / FileSystem / Process 未列入官方分级表，但风险同等，建议一并纳入裁剪考量。

遥测默认开启（PostHog）：上报工具名/成败/耗时/客户端版本，不采集参数与输出，仅本地随机 UUID；ANONYMIZED_TELEMETRY=false 关闭。
官方明确建议：高敏感/合规环境用 VM 或 Windows Sandbox；个人机要关高危工具 + 定期备份 + 实时监督。

5. 与同类对比优劣

5.1 vs 同类 Windows 桌面 MCP（GitHub 搜索 windows-mcp，289 个仓库）

项目	Star	技术栈	定位
CursorTouch/Windows-MCP	7,581	Python + UIA	品类头部，断层第一
shuyu-labs/Windows-MCP.Net	233	C#	.NET 系替代
mario-andreschak/mcp-windows-desktop-automation	118	AutoIt	AutoIt 脚本路线
sbroenne/mcp-windows	101	C#	同样按名操作 UIA，量级小
mukul975/mcp-windows-automation	56	Python	80+ 工具但社区小

5.2 vs 技术路线

维度	Windows-MCP（a11y 树）	截图+视觉路线（Anthropic CU / Hermes computer_use / UI-TARS）	mcp-chrome / BrowserSkill（浏览器扩展）
模型要求	✅ 任意 LLM，vision 可选	需要视觉模型	任意
token 消耗	低（树文本）	高（视觉路线 20 步约 30K tokens 上下文）	低（无障碍树）
覆盖范围	✅✅ 整个 Windows 桌面+系统工具	✅✅ 整个桌面	❌ 仅浏览器
单步延迟	0.2~0.5s	视觉推理较慢	快
系统级工具（PS/注册表/进程）	✅	❌	❌
模糊场景（自绘 UI/游戏）	❌ UIA 够不着	✅ 视觉兜底	—

结论：桌面应用自动化选 Windows-MCP（省 token、模型自由、系统工具全）；自绘界面/游戏选视觉路线；浏览器内操作用 mcp-chrome/BrowserSkill。

6. 社区反馈 / 可靠性

指标	数据（2026-10-01 实测）
GitHub Star / Fork	7,581 / 895
Open Issues	30（相对体量很干净）
PyPI 下载（windows-mcp）	日 2,742 / 周 12,362 / 月 27,463，上升期
版本	v0.8.7（2026-09-30 发版），Beta 未到 1.0
背景	个人开发者组织（非大厂官方），有 Discord/X 社区、MseeP 安全评估、Trendshift 榜单

可靠性结论：品类第一、更新极活跃、下载量健康，可以放心用；注意 1.0 前 API 可能变动，锁定版本更新节奏即可。

7. 资源消耗

运行时依赖 17 个包：fastmcp≥3.0（MCP 框架）、comtypes + pywin32 + uia（UIA/COM 绑定）、dxcam + pillow（截图后端，auto 顺序 dxcam→mss→pillow）、psutil（进程）、posthog（遥测）、thefuzz/python-levenshtein/fuzzywuzzy（模糊匹配元素名）、markdownify、tabulate、pygments、requests、click、platformdirs、uuid7。整体轻量，无 GPU/无数据库。
Python ≥ 3.14（pyproject 实锤；README 徽章 3.13+ 过时）——装前先确认本机 Python 版本。
安装体积/时间：uvx 首次拉依赖 1~2 分钟；uv tool install windows-mcp 固定安装后 exe 约 1 个 uv 工具体积。
常驻进程：windows-mcp install 模式下单 Python 进程常驻（计划任务），所有 agent 共享一个实例；stdio 模式则每个 agent 各起一个进程。
进程内存/CPU（2026-10-04 复测，含泄漏验证）：已提交内存 ~320 MB 为启动即有的常态（Python 3.12 + fastmcp/uiautomation/PIL/模糊匹配库全量导入；启动瞬间物理驻留 ~~119 MB，空闲后被系统压缩到 16~~120 MB 区间，非泄漏）+ venv 启动器壳 3.3 MB；连打 3 次全量 Snapshot 仅 +0.5 MB 内存 / +0.1s CPU——无每调用泄漏；启动耗 CPU ~2.6s，空闲近零（UIA 树按需构建，WatchDog 默认关闭）。
磁盘：uv venv 152 MB（%APPDATA%\uv\tools\windows-mcp\）+ ~/.windows-mcp/ 配置与日志 79 KB；uv 全局缓存另计（多工具共享）。
网络：仅 127.0.0.1:8000 单监听，无主动外联（遥测已关）。
token 消耗（2026-10-04 实测，16 开窗桌面）：Snapshot 全量树 36.9 KB ≈ 1.2~1.8 万 token（体量随窗口数线性涨，最大头）；Screenshot 快速路径 129 KB（含 base64 截图，视觉 token 另计）；use_vision=false + 关少窗口是省 token 关键；延迟：Snapshot 6.9s（全桌面 UIA 遍历）、Screenshot 0.19s。高分辨率屏（1440p/4K）截图可能超 Claude Desktop 1MB 工具结果上限，用 WINDOWS_MCP_SCREENSHOT_SCALE（0.1~1.0，0.5 即面积 1/4）降采样。
延迟：单步动作 0.2~0.5s（受系统负载和 LLM 推理速度影响）。
杂项开关：截图后橙红闪光提示可 WINDOWS_MCP_DISABLE_FLASH=1 关；WINDOWS_MCP_WATCHDOG 默认关（开了会在不稳定的 UIA 环境下长期运行崩溃）。

8. 安装方式推进：全局共享方案（所有 Agent 共用）

诉求：所有 agent（zcode / Hermes / dsh / WorkBuddy / Claude Code / Codex CLI…）共用这一套桌面操控能力，不想每个 agent 各装一份。结论：✅ 官方原生支持，方案 A。

8.0 uvx vs uv tool install（为什么选后者）

uvx：临时跑一次（类比 npx）——环境即用即弃、exe 不落 PATH、每次解析最新版，适合试玩
uv tool install：持久化——包进独立 venv（%APPDATA%\uv\tools\<名>\）、入口 exe 固定到 ~\.local\bin\、版本锁定，uv tool upgrade / uninstall 管理
uv 会按包的 requires-python 自动下载缺失的 Python 到 %APPDATA%\uv\python\（本机已有 3.11.15 / 3.12.12，系统 Python 不动）；下载缓存统一在 %LOCALAPPDATA%\uv\cache\

8.1 方案对比

方案	做法	优点	缺点
A. 常驻共享服务（推荐）	`windows-mcp install` 注册每用户登录自启计划任务（任务名 `windows-mcp-server`），默认 streamable-http @ 127.0.0.1:8000；所有 agent 以 HTTP 型 MCP 接同一 URL	单实例省资源；工具裁剪/遥测配置一处生效；所有端同步获得能力	多 agent 并发调用同一桌面时动作会互相打架（天然串行场景下无碍）
B. 每 agent 独立 stdio	各端配置 `uvx windows-mcp serve`（README 标准姿势）	隔离好、配置自由	N 份 Python 进程、N 处配置，重复占用
C. 固定安装	`uv tool install windows-mcp` 得到 `windows-mcp.exe`	版本可控、不依赖 PATH（MSIX 版 Claude Desktop 必须用这种）	多一步管理

方案 A 源码实锤（__main__.py install 命令）：默认 --transport streamable-http --host 127.0.0.1 --port 8000（stdio 不支持作为服务），自动创建 ~/.windows-mcp/start-server.cmd 包装脚本 + 计划任务并立即启动，日志在 ~/.windows-mcp/server.log / server.error.log。

8.2 安全性（方案 A 关键前提，源码+SECURITY.md 确认）

loopback（127.0.0.1）绑定免认证：HTTP 传输只在非 loopback 绑定时才强制 auth（无 auth-key 且无 --allow-insecure-remote 会拒绝启动），本机共享不用配 token。
默认不发 CORS 头（任意网页无法跨域打到它）+ 自动 DNS rebinding 防护；要更稳可加 --auth-key（所有 agent 配置同步带上）。
强烈建议裁剪高危工具：config.toml 里 [tools] exclude = ["PowerShell", "Registry"]，按需放开；遥测 ANONYMIZED_TELEMETRY=false。

8.3 各 Agent 接入（共用 URL：`http://127.0.0.1:8000/mcp`）

实际端点无尾斜杠（uvicorn 日志为准）；streamable-http 默认带 Mcp-Session-Id 连接态，重连频繁可开 WINDOWS_MCP_STATELESS_HTTP=1；WSL 里的 agent 要经 powershell.exe 桥接回 Windows 侧。

2026-10-01 接入记录（用户明确只配 zcode + Hermes 两端，dsh 不管；Codex 09-19 已卸载、WorkBuddy 09-25 已卸载、Claude Code 未装）：

Agent	配置位置	状态
ZCode	`~/.zcode/cli/config.json` → `mcp.servers` 加 `{"type":"http","url":"http://127.0.0.1:8000/mcp","enabled":true,"timeoutMs":60000}`	✅ 已写入（备份 Temp/config.json.bak-20261002），下次会话生效
Hermes	`%LOCALAPPDATA%\hermes\config.yaml` → `mcp_servers.windows-mcp: {url: ..., enabled: true, auth: none}`	✅ 已写入 + `hermes mcp test` ✓ Connected（Auth: none，18 工具）；Desktop 重启后不再弹 OAuth 登录卡（见坑④）
dsh	—	❌ 用户明确不需要

接入坑：hermes mcp add --url ... 会挂死不落盘（>2 分钟无输出，已杀进程），改用 hermes config set mcp_servers.<名>.url + .enabled 两键即可；hermes mcp test <名> 能直接验证 url-only 配置，不必重启 Desktop。

8.4 执行记录（2026-10-01 已完成）

✅ uv tool install windows-mcp → PyPI 实装 0.8.5（GitHub release 已到 v0.8.7 但未推 PyPI），跑在 uv 自管 Python 3.12（PyPI 0.8.5 元数据不强制 3.14；仓库 main 的 pyproject 才是 ≥3.14）；venv 在 %APPDATA%\uv\tools\windows-mcp\，exe 在 ~/.local/bin/
✅ windows-mcp install → 计划任务 windows-mcp-server（登录自启 + 立即启动），包装脚本 ~/.windows-mcp/start-server.cmd 钉死 venv 解释器（源码 _resolve_program 返回 sys.executable -m windows_mcp）；首次冷启动 ~15 秒才开始监听，不是失败
✅ ~/.windows-mcp/config.toml：[tools] exclude = ["PowerShell","Registry"]（实测生效，tools/list 18/20）；config.toml 没有遥测键——用 setx ANONYMIZED_TELEMETRY false（用户级环境变量，计划任务可读）
✅ 协议验证：initialize 200 + tools/list 18 工具 + tools/call Notification 真实弹 toast 成功（端到端全通）
✅ 资源实测回填第 7 节（RSS 94.2 MB）
✅ a11y 树 token 消耗已实测回填第 7 节（2026-10-04：Snapshot 36.9KB≈1.2~1.8 万 token / 6.9s，内存 ~320MB 提交无泄漏）；Hermes Desktop 端 OAuth 误判已修复（坑④），重启 Desktop 验证

坑记录：① install 内部调 schtasks/PowerShell 输出 GBK 中文，Python 按 UTF-8 解码刷 UnicodeDecodeError——不影响注册结果，忽略；② Git Bash 里 curl -d 带中文 JSON 会因 GBK 传参变非法 Unicode（服务端报 Parse error），工具调用参数用纯 ASCII；③ bash printf 写中文注释进 config.toml 会编码损坏，配置文件一律纯 ASCII；④ ~~Hermes Desktop 弹 “Sign in to Windows MCP”/OAuth 报错~~（根因：开机时 Desktop 与 windows-mcp 计划任务同时启动，服务端冷启动 ~15s 内 Desktop 探测超时，而 Hermes 探测超时错误文本自带 “OAuth” 字样，前端 NEEDS_AUTH_RE 把它误判成 needs-auth 弹登录卡。修复：config.yaml 条目加 auth: none（字符串）显式免认证，登录按钮被前端 canAuthenticate 抑制；注意 hermes config set ... auth none 会把值解析成 YAML null、'"none"' 会连引号存入——都不对，直接编辑 config.yaml 写裸 none）；⑤ 【重要误判纠正 2026-10-04】Snapshot use_ui_tree=false 时输出 “No windows found / No elements” 是官方设计的快速路径（源码注释：fast path 跳过窗口枚举，防 UIA 在应用启动无响应时挂起）——不是故障！误判它为”UIA 崩坏”烧掉大量排查时间。要窗口列表/语义树必须用默认 use_ui_tree=true；⑥ 真实短板（2026-10-04 实测）：Chromium/WebView 弹窗（如 Qoder Rewards）加载中会让 UIA 调用长时间挂起——WaitFor 首先卡死（60s 超时），随后服务进程的 Snapshot 跨重启持续卡死（curl 直发 90s 只回 SSE ping），但前台进程跑同一份 Desktop().get_windows() 秒出 13 窗口，VDM/apartment/会话隔离假设全部排除；卡点疑似 fastmcp 线程池与 COM 初始化顺序交互，机制未明。缓解：webview 应用忙时只用 Screenshot（fast path）+ WaitFor 慎用；卡死就 schtasks /End + /Run 重启服务（zcode http 客户端会自动重连，DisplayInventory 等非 UIA 工具全程可用）。

refer

CursorTouch/Windows-MCP（GitHub 仓库）

windows-mcp · PyPI / PyPI 下载统计

SECURITY.md（官方安全策略：工具风险分级/遥测范围/网络策略）

本机知识库关联：《LLM 操控电脑浏览器.md》（abbrlink 6736，3.2 节桌面控制 MCP 类目）