Windows-MCP

用途 · 功能与边界 · 下载安装 · 工具清单 · 更新记录 · 参数参考

工具用途

Windows-MCP 是运行在本机的 Windows 自动化 MCP 服务。连接 Claude Code、Codex 桌面端、DeepSeek Harness、Gemini CLI、Zcode 或 Trae 后，AI 可以读取真实窗口和控件、操作应用和网页，并通过状态或文件结果核对任务。模型与 AI 客户端由你选择，本项目不提供模型账号或云端算力。

当前稳定版：v1.5.0，文档更新于 2026-10-27。 本版整合前三批引擎、文本效率、窗口视觉与部署配套升级；正式安装包、验证记录和校验值以 GitHub Releases 为准。完整版本变化见 CHANGELOG。

适合窗口控件操作、表单填写、应用内文本编辑、重复桌面流程和结果检查。网页聊天或云端模型需要能够连接本机 MCP 的客户端，打开本仓库网页不会自动获得桌面控制能力。

以上为本版源码在隔离验收环境中的真实界面截图；客户端检测状态为测试夹具数据。

本项目基于 CursorTouch/Windows-MCP 二次开发，遵循 MIT 许可证，保留上游及第三方组件的许可声明。

Related MCP server: Windows-MCP

功能简介

1.5.0 的三批升级

本版保留全部兼容工具。64 项升级候选并未全部实施；尚未交付完整任务队列治理、全引擎 DPI/坐标统一、OmniParser、ODR 宿主适配、Agent Workspace 等工作，不将候选能力算作现成功能。

观察、操作、核对

1. 观察：优先使用 Observe、Find 或指定窗口的 Snapshot，选择当前会话返回的目标 ID。

2. 操作：Execute 优先选择支持的 UIA 模式；需要真实输入时检查前台、窗口身份和遮挡。Browser 操作独立 Playwright 会话，NativeAPI 操作明确授权的文本文件。

3. 核对：提供 expected，或调用 Verify 读取独立后置条件。VERIFIED 表示条件已得到证据支持；DISPATCHED_UNVERIFIED 只说明动作已派发。

Observe(window="目标窗口的唯一标题")
Execute(target="本次观察返回的目标 ID", action="set_value", value="准备填写的文本")
Verify(expected={"kind":"element_state", "target":"目标 ID", "state":{"value":"准备填写的文本"}})

以上是 MCP 工具调用示意，不是 PowerShell 命令。实际参数以客户端发现的工具模式为准；动作须具有匹配授权。发送、提交、删除等动作若已派发但未证实，应先检查结果，避免重复执行。

工具 profile

profile 只决定公布哪些工具，不授予额外权限。精简 profile 的 --tools / --exclude-tools 只能进一步缩小范围。管理器默认安装 full；自定义接入示例见安装指南。

文本、图片与浏览器

• 文本：Observe(target=..., detail="text"/"selection") 读取控件内容；Execute 支持 select_text、replace_text、delete_text、append_text。多处匹配须明确一基 occurrence，不静默改写整篇富文档。

• 局部观察：Observe(target=...) 观察子树；mode="refresh" 批量回读同一窗口最多 100 个已有目标。Watch 在事件后回读相关控件，最长 1.5 秒兜底。

• 视觉：Visual 的 region 是未缩放捕获图的像素区域，返回图的点击坐标再由服务映射回物理桌面。窗口移动、调整大小、进程生存期变化、引用过期或点击被遮挡时拒绝输入。

• 图片变化：previous_target、only_if_changed 可省略未变图片，仍返回新视觉引用。变化仅是重观察提示，不算业务验证。

• 浏览器：独立 Playwright profile，支持页面、iframe、表单与弹窗。可使用已安装 Edge；其他通道需要相应浏览器。服务不提供用户原始 Cookie、任意 JavaScript 或 CDP 连接。

操作授权与升级迁移

从 1.4.x 升级后，旧的全局全自动授权不会继续放行。 先发起具体待审请求，再由本机操作员核对客户端会话、应用、工具、参数和期限。勾选“全自动”并批准，为所示范围开启默认最长 8 小时的自动 R2 授权；重连生成新会话后须重新授权。通过“操作授权… → 撤销授权”撤销，AI 不能操作自己的审批窗口。

浏览器导航、重定向和子资源均检查 origin；顶层 GET 可逐跳检查后继续，表单和子资源的 HTTP 重定向当前会被阻止。审批窗口打开期间暂停 MCP 桌面输入。已进入 UIA provider 的动作无法由 Python 强制取消；ACTION_IN_PROGRESS 后用 Session 查询完成，独立核对后再 acknowledge，cancel/resume 不隐式清除未决动作。

这些措施降低本机自动化风险，不构成操作系统沙箱；普通权限无法绕过 UAC、安全桌面、锁屏或管理员窗口边界。默认关闭 PostHog 遥测。完整处理规则与离线政策见管理器“关于”和 按需参考。

微软组件与可选条件

OCR 实际识别尚未在当前验收机通过：该机无包标识、无 Tesseract 引擎。不要将组件探测或握手成功理解为具体应用任务已经完成。

安装指南

Windows x64 安装版与便携版

从 最新正式 Release 下载对应版本，核对 SHA256SUMS.txt。两种格式均包含管理器、Skill、MCP 服务、Python 运行时及依赖，不必另装 Python。当前页面功能对应 v1.5.0；请在发布页核对所下载资产的版本。

安装版默认路径为 %LOCALAPPDATA%\Programs\Windows-MCP，按用户安装，无需管理员权限；系统卸载入口位于 Windows“设置 → 应用”。卸载管理器会保留已接入的 Skill/MCP 和个人数据，对应接入须在管理器中单独卸载。

便携版请保留 WindowsMCP.portable.json 和整个目录，不在 ZIP 内运行。接入后保持目录位置，移动或删除前先卸载接入；加密审批数据仅供原 Windows 用户使用。

首次接入

1. 打开管理器，在左侧选择检测到、尚未接入的客户端，可多选。已安装项带圆点并禁用重复安装。

2. 点击“安装 Skill + MCP”，核对真实路径与操作预览，再执行安装。

3. 等待版本、31 个工具、完整模式和 Session READY 验证通过。重启目标客户端或新建会话。

4. 在目标客户端确认工具已出现，先读取一个明确窗口，再执行具有授权的操作。

5. 若需要指定客户端程序目录，进入“设置 → 高级设置”，添加真实文件夹并点击“检测”，保存后应用。

Codex 的目标是 Codex 桌面端，管理器不安装或调用 Codex CLI。文件写入前创建事务备份，失败按校验结果回滚，保留其他 MCP、JSONC 注释与个人配置；仍有客户端引用时保留共享服务。

~ 表示当前用户主目录。支持 CODEX_HOME、DSH_HOME 等实际目录设置；DeepSeek 桌面版和 CLI 共用 Harness Home。OpenCode 保留旧接入的维护与卸载，不提供新安装入口。配置格式与参数细节见 按需参考。

更新、修复、备份和卸载

• 更新：设置中“检查更新”发现版本后显示红点，用户点击“更新安装”才下载，先校验 SHA-256。安装版保留原位置；便携版保留 data，由独立助手替换、重启并验证，失败保留回滚副本。

• 升级接入：更新管理器后检查受管接入是否也完成升级和验证；已运行的 MCP 进程需由客户端重连后使用新版本。

• 验证与修复：右侧提供连接验证和修复；健康检查明确区分版本、工具清单、模式、Session 结果及可选组件状态。OCR 缺失只作单独提示。

• 备份与撤销：支持预览备份恢复、撤销安装批次；后续个人修改或共享引用存在时报告冲突，不强行覆盖。

• 卸载：从独立卸载窗口选择具体客户端接入，保留其他配置与仍被引用的运行时。

管理器保留固定三面板布局、浅白/暖色护眼/深色/跟随系统主题、独立日志背景、常规/玻璃拟态视觉强度、真实任务进度及六个离线“关于”页面。界面图是实拍，版本与接入是否更新以程序内真实验证结果为准。

源码安装与开发

需要 Windows、Python 3.12+、Git 和 uv。在项目目录执行：

git clone https://github.com/CyanQX/Windows11-mcp.git
cd Windows11-mcp
uv sync --frozen --extra browser --extra capture --extra ocr
uv run --frozen --extra browser --extra capture --extra ocr windows-mcp doctor
uv run --frozen --extra browser --extra capture --extra ocr windows-mcp serve

serve 默认使用 stdio，终端等待客户端连接属于正常行为。开发管理器再添加 --extra installer，运行测试再添加 --extra dev；构建另需 --group build。为保持环境稳定，同一环境后续 uv run 使用相同 extras。WGC 可选依赖当前限 Windows x64，OCR 不会自动安装外部引擎和语言。

将上面同步完成的项目 .venv\Scripts\windows-mcp.exe 作为自定义客户端的 command，参数为 ["serve"]；精简接入改为 ["serve","--profile","ui-core"]。Skill 可从仓库 skills/windows-mcp 复制到客户端 Skill 目录。通过管理器安装的用户无需自行编辑配置。

测试使用 uv run --frozen --extra dev --extra installer --extra browser --extra capture --extra ocr pytest；默认不发送真实桌面输入。只有显式启用 WINDOWS_MCP_DESKTOP_TESTS=1 才执行专用夹具中的真实输入，具体安全边界见 开发说明。CI 检查 Python 3.12/3.13 与两代 FastMCP/MCP；本地前三批在 Python 3.14.7 验证，不能据此承诺所有系统/应用组合。

诊断、微软配套和固定清单

以下命令用于已安装的控制台服务；打包版也可用 Windows-MCP.exe 对应子命令，并用 --output 写出诊断文件。

windows-mcp doctor --output doctor.json
windows-mcp connectors --probe --output connectors.json
windows-mcp manifest --profile ui-core --output ui-core.manifest.json
windows-mcp serve --profile ui-core --static-manifest ui-core.manifest.json

connectors --probe 只核对 WinGet 初始化和 tools/list，不搜索或安装软件、不改客户端配置。各微软 server 的权限独立。静态清单须使用实际 SDK/profile 重新生成；启动检查不接受动态过滤，生成清单也不替代 ODR 注册。

可信配置可指定文件范围；只授权任务实际需要的目录：

[tools]
profile = "full"

[policy]
workspace_roots = ['E:\my-authorized-task']
allow_r3 = false
# 可选：本地操作员预设准确的 HTTP(S) origin。
allowed_network_origins = ['https://github.com']

默认文件范围为 ~/.windows-mcp/workspace；便携模式为 data/config/workspace。远程 HTTP 传输需要鉴权、TLS 和 IP 白名单等条件，配置路径及完整环境变量见 按需参考。

常见问题与验证范围

Windows 11 是当前本地验收平台。Win32 与 WPF 专用夹具、浏览器协议和两代 SDK 已有回归；Windows 10、物理混合 DPI 多屏、所有输入法及第三方客户端/Office 组合没有完整验收承诺。性能基准按应用测量，缓存减少往返不一定降低总耗时。

反馈问题时附程序版本、工具、状态码和复现步骤，先去除凭证、输入正文、业务文件和个人信息。GitHub 发布页提供校验值及构建验证记录；完整日志可能含本机路径，请核对后再共享。政策与联系信息见管理器“关于”，联系邮箱为 jingyanx2@gmail.com。

工具一览

共 31 个工具：11 个只读、20 个会改变系统状态。只读标记描述工具的效果，具体调用仍受服务权限策略约束。