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

工具用途

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

本次发布：v1.6.0，文档更新于 2026-11-14。 整合第四至第六批统一真实输入、自然移动、动态控件跟随、人工接管、视觉落点复核和捕获进程复用。安装包在发布流水线完成后提供；正式安装包、验证记录和校验值以 GitHub Releases 为准。完整版本变化见 CHANGELOG。

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

以上为 v1.5.0 在隔离验收环境中的真实界面截图（管理器布局沿用）；客户端检测状态为测试夹具数据。

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

功能简介

第四批：统一鼠标输入（1.6.0）

1.6.0 整合第四至第六批：第四批统一输入、目标复核和执行记录；第五批提供自然移动、动态目标和人工接管；第六批完成视觉局部复核、捕获进程复用和跨进程桌面协调。

开启鼠标优先，可在当前使用的服务配置文件中加入：

[interaction]
mode = "pointer"

也可用控制台参数启动：windows-mcp serve --interaction-mode pointer，或设置环境变量 WINDOWS_MCP_INTERACTION_MODE=pointer。优先级为命令行 > 环境变量 > 配置文件；未设置时仍为 semantic，保持既有自动路由。保存配置后重启 MCP 服务并重连客户端，用 Session(operation="status").interaction_mode 核对实际模式。模式只选择执行方式，沿用现有操作授权。

已有接口也支持单次指定真实鼠标：Observe(window="目标窗口") → Execute(target="返回的目标 ID", action="click", mode="physical")。按下前检查与输入发送之间仍可能发生界面变化，失败或未验证时应先重新观察结果；取消无法撤销已送到应用的操作。

第五批：自然移动与动态目标（1.6.0）

第五批的物理鼠标默认采用 natural 控制器：根据距离和目标大小选择约 0.12–0.8 秒的移动时间，使用五次平滑速度曲线，接近目标时减速。控制器以 90 Hz 为调度目标，实际频率取决于 Windows、UIA provider 和机器负载；空间路径默认直线，不加入随机抖动。显式拖拽 duration 仍控制该段移动时长。

• 本地反馈与目标跟踪：读取实际光标位置，容许输入队列的短暂投递延迟，再对残余误差进行有限修正。有控件身份的目标使用 UIA/窗口变化事件唤醒刷新，并以约 100 毫秒的定向回读兜底；移动后再强制复核。目标移动会调整路径，替换、隐藏、禁用或持续不稳定时停止，最多三次重新规划。此过程不请求截图，也不需要模型逐帧指挥。
• 悬停与按压：悬停默认等待 400 毫秒；普通点击到达后短暂稳定，再以约 50 毫秒的按压完成一次点击。悬停等待是有上限的停留，不保证每个应用都会显示菜单或提示。
• 外部输入接管：鼠标手势期间，通过独立消息线程监听外部鼠标/键盘输入，保留用户输入，停止本次后续输入并清理本次按住的按钮。当前客户端会话暂停，Session.pointer_interruption 返回原因。核对已经发生的结果，等待用户明确继续后再调用 Session(operation="resume")；客户端不应自行抢回控制。输入标记用于区分本服务事件，不是安全边界，也不把其他软件注入误称为硬件操作。
• 可核对的运行记录：桌面 Execute.dispatch.motion 返回 style、elapsed_ms、samples、replans、max_feedback_error_px、stop_reason、human_takeover、window_events；Session.last_pointer_motion 也提供最近一次记录。max_feedback_error_px 是命令与回读之间的最大差异，包含投递延迟，不等于最终点击误差；业务结果仍需要 expected / Verify。

推荐配置：

[interaction]
mode = "pointer"
pointer_motion = "natural"
hover_ms = 400
human_takeover = true

控制台可用 windows-mcp serve --interaction-mode pointer --pointer-motion natural；WINDOWS_MCP_POINTER_MOTION 对应移动策略。pointer_motion="legacy" 保留第四批固定时序，不启用新的悬停停留和接管监测；hover_ms 为 0–2000 的整数。human_takeover=false 关闭自然手势期间的外部输入监测，协作取消仍保留；Session.human_takeover 显示实际是否启用。两种移动策略均沿用相同授权边界；Win32 原生下拉列表必须通过 GetComboBoxInfo 证明归属，不能只凭进程或窗口类名放行。

控件身份跟踪不适用于裸坐标、视觉图内坐标或旧批量坐标路径。接管只暂停当前会话的鼠标手势；跨进程桌面工作互斥见第六批。UIA provider 读取如果阻塞，Python 无法强制中断，停止和释放可能延迟；这些机制不提供硬实时或操作系统沙箱保证。

第六批：视觉复核、进程复用与桌面协调（1.6.0）

• 捕获进程复用：WGC / PrintWindow 按需请求共用一个串行原生辅助进程，复用解释器和组件导入；每次仍重新取帧，WGC 会话仍逐次创建，不返回历史帧，也不在后台持续录像。OCR 和依赖探测继续使用独立的一次性进程。
• 明确的故障边界：单次原生请求默认 12 秒，超时结束整个 Job Object 并回收进程；失败请求不自动重发。下一次明确请求再创建进程，读取器校验响应长度及请求编号；服务关闭时回收辅助进程。
• 视觉点击前局部核对：保存有界的本地参考图，鼠标到达后、按下前，仅在本地重新取帧并比较落点周围最多 33×33 个图像像素。考虑 ROI、缩放和负屏坐标；局部内容变化返回 TARGET_STALE，要求重新观察。再次核对窗口生存期、几何、前台和遮挡后才允许按下；没有自动追图、换点或失败重点击。像素相同不能证明控件身份，动画、悬停样式或文本变化可能要求重新观察。
• 跨进程桌面工作互斥：同一 Windows 登录会话中的新版服务共用命名互斥量，覆盖每段桌面线程工作，包括鼠标手势与同步 UIA。被占用时以 DESKTOP_BUSY 拒绝尚未开始的工作，不排队补点；UIA 超时仍执行时继续持有，直到实际结束；进程退出后由 Windows 释放。其他自动化软件不参与，已有旧版本服务也不参与；这不是系统级输入隔离。多段工具调用不构成一个跨步骤事务。
• 节省重复输出：only_if_changed 在图像未变且不需要 OCR 时跳过 PNG 编码与图片传输，仍读取新帧。每会话最多保留 8 张参考图、合计 1600 万像素；视觉引用保留 60 秒有效期，可能因容量提前失效。
• 可测量状态：Session.capture_worker 提供进程、请求、启动、超时和最近耗时；Session.desktop_coordination 提供当前占用状态。Visual.capture_elapsed_ms 是捕获/准备图片的耗时，不包含后续 OCR；可用 uv run python scripts/benchmark_capture.py --hwnd <窗口句柄> --backend printwindow --count 6 测量冷启动和后续请求，数据随应用与机器变化，不承诺固定提速倍数。

语义控件仍优先使用 Observe/Execute；无控件画布再显式使用 Visual。自然鼠标移动和控件跟随无需截图；只有视觉坐标点击增加一次本地图片复核，不将图片发给模型。UIA provider 阻塞、受保护画面、最小化窗口、不同权限级别和安全桌面仍可能不可用。

1.5.0 的三批升级

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

观察、操作、核对

1. 观察：优先使用 Observe、Find 或指定窗口的 Snapshot，选择当前会话返回的目标 ID。
2. 操作：Execute 默认优先选择支持的 UIA 模式；可通过 interaction.mode 切换自动点击的鼠标优先策略。真实输入检查窗口身份和遮挡；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.6.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 发布页提供校验值及构建验证记录；完整日志可能含本机路径，请核对后再共享。政策与联系信息见管理器“关于”，联系邮箱为 [email protected]。

工具一览

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