MCP Windows Desktop Automation

MCP Windows 桌面自动化

面向交互式 Windows x64 桌面的可信所有者 MCP 服务。版本 2 保留了原有的 50 个 AutoIt 工具和 7 个提示词，新增了实际 PNG 截图，并通过 SDK 2.0.0 支持 MCP 2026-07-28。明确的兼容性支持旧版 2025-11-25 客户端。

运行

需要 Node.js 22 或更高版本。安装此仓库或经过审核的发布包，然后运行已安装的命令：

npm ci
npm run build
node dist/index.js --transport=stdio
# After installing the package:
mcp-windows-desktop-automation --transport=stdio

Stdio stdout 仅包含 MCP JSON 消息。诊断信息（包括详细操作名称）会输出到 stderr，不含参数值。关闭 stdin 会关闭服务及其本机辅助程序。

本机操作需要 Windows x64 和已登录用户的交互式桌面。枚举和协议处理也可在 Linux 上运行，但本机调用会返回明确的平台错误。不支持 ARM64、会话 0 中的服务、无头 Windows 会话、其他用户的会话，以及超出服务权限的提升权限窗口。不涉及任何提供商账户或模型。

传输方式与所有权

默认使用 Stdio。使用 HTTP 时，请设置：

• MCP_AUTH_TOKEN：至少 32 个字符的随机所有者 bearer token。
• MCP_FILE_ROOTS：现有本地目录的 JSON 数组，例如 ["C:\\Users\\me\\Documents"]。
• 可选的 MCP_ALLOWED_HOSTS：以逗号分隔的精确 Host 值，使用端口时也须包含端口。
• 可选的 MCP_ALLOWED_ORIGINS：以逗号分隔的精确来源。

然后启动 mcp-windows-desktop-automation --transport=streamable-http --port=3000。端点为 http://127.0.0.1:3000/mcp；--host=ADDRESS 可显式更改默认的 loopback 地址。每个端点请求都必须经过授权。Host 和 Origin 会进行精确检查；不信任转发标头，也不会启用宽松的 CORS。远程部署请使用可信的 TLS 反向代理。

每个进程只有一个所有者，共用同一桌面、剪贴板、本机选项和串行命令队列。所有持有该令牌的客户端都拥有相同的广泛 OS 权限，包括启动进程、传递给 runAs 的凭据以及关机权限。不同所有者应部署在不同的 Windows 账户、会话和进程中。文件根目录仅约束文件资源；自动化工具并不是 OS 沙箱。这种私有 bearer 部署不实现 OAuth，也不声称提供多租户授权。

HTTP 支持当前的 Streamable HTTP 和有意保留的无状态旧版请求。当前客户端必须发送相互匹配的标准 MCP 协议、方法和名称标头。不提供旧式 SSE 会话端点。此前的 --transport=websocket 分支只是一个不起作用的占位项；现在它会提示迁移，而不会再声称支持 WebSocket。

保留的工具和提示词

分组	工具
鼠标	mouseMove, mouseClick, mouseClickDrag, mouseDown, mouseUp, mouseGetPos, mouseGetCursor, mouseWheel
键盘和剪贴板	send, clipGet, clipPut, autoItSetOption, opt, toolTip
窗口	winActivate, winActivateByHandle, winActive, winClose, winExists, winGetHandle, winGetPos, winGetText, winGetTitle, winMove, winSetState, winWait, winWaitActive, winWaitClose
控件	controlClick, controlClickByHandle, controlCommand, controlGetText, controlSetText, controlSend, controlFocus, controlGetHandle, controlGetPos, controlMove, controlShow, controlHide
进程	run, runWait, runAs, runAsWait, processExists, processClose, processSetPriority, processWait, processWaitClose, shutdown
截图	takeScreenshot

提示词：findWindow, windowInfo, fillForm, submitForm, automateTask, monitorWindow, takeScreenshot。

现有的 AutoIt 参数约定保持不变。字符串和整数现在都有明确的限制。等待超时时间以秒为单位，默认值为 10，范围为 1–25；旧版进程超时说明错误地写成了毫秒。点击次数上限为 100。文本获取工具使用固定的 UTF-16 缓冲区（默认值和最大值均为 65,536 个代码单元）；缓冲区过小时会报告错误，而不会静默截断文本或无限分配内存。

实际截图和文件资源

takeScreenshot 会返回 MCP image/png 内容：

• { "target": "fullscreen" }：虚拟桌面上的可见像素。
• { "target": "window", "windowTitle": "..." }：使用 Win32 PrintWindow 进行 AutoIt 窗口选择。
• { "target": "region", "x": 20, "y": 20, "width": 100, "height": 80 }：完全位于虚拟桌面内的矩形区域。

资源提供 screenshot://desktop 和 screenshot://window/{percent-encoded-title}。它们取代了旧版仅有文本的截图占位内容。截图使用随附的静态 Windows PowerShell 脚本；请求数据通过 JSON stdin 传入。截图不会保存到磁盘。PNG 限制为 3,200 万像素和 8 MiB，辅助程序的截止时间为 15 秒。不同应用对 PrintWindow 的支持各不相同；受保护、最小化或使用硬件渲染的窗口可能会拒绝截图或生成空白像素。截图不会激活窗口。

file:/// URI 可读取规范化配置根目录中的本地文件或目录列表。Stdio 默认将工作目录设为根目录；HTTP 必须显式指定根目录。文件必须是常规文件且大小不超过 1 MiB，并以 base64 二进制资源内容返回；目录最多返回 1,000 个名称。网络主机文件 URI 和逃逸出根目录的符号链接都会被拒绝。这是对原先无限制文件访问的有意替代。

取消和关闭

一个自有的原生辅助程序负责将 AutoIt DLL 与 MCP 事件循环隔离。队列中最多可有 16 个工具／资源任务；每个桌面请求的总截止时间为 30 秒。原生选项会一直保留到辅助程序停止。取消、超时或原生崩溃都会中断该辅助程序；后续请求会启动一个使用默认选项的新辅助程序。中断的操作不会重放。已经应用的桌面更改不会撤销，通过 run/runAs 有意启动的应用也不会自动终止。

取消功能适用于活动的 stdio 请求，包括数字请求 ID 0。对于无状态的旧版 HTTP，关闭活动响应会取消该请求；单独的旧版取消通知无法针对其他请求。停止服务器会阻止工作进程重启，并关闭传输连接。

开发与验证

npm run check
npm run test:package
npm audit --omit=dev --audit-level=high

CI 在 Linux 和 Windows 上运行 Node 22 和 24。Windows 任务要求针对唯一归属的 WinForms 测试夹具执行实际 AutoIt 调用、Unicode 控件与剪贴板往返测试、有界文本测试、屏幕截图像素检查、取消测试以及助手清理。Linux 任务仅跳过该平台专属的原生测试夹具。两个平台都会测试实际的新旧线协议消息、私有 HTTP 边界、客户端 ID 并发重叠、文件根目录越界、已安装软件包的可执行文件、干净的标准输出以及 EOF。

没有测试会调用 shutdown、runAs 或任意应用程序。原生测试夹具会还原剪贴板文本，并关闭仅由其自身创建的窗口。Windows 桌面行为会在一次性运行器中验证；与所有第三方桌面应用程序的兼容性仍取决于相应应用程序的控件和权限。

SDK 迁移遵循官方 v2 指南和2026 协议指南。原生自动化使用 node-autoit-koffi，并通过捆绑的 AutoIt DLL 执行有界调用。屏幕截图遵循 Microsoft 的 PrintWindow 和 CopyFromScreen API。