🖱️ desktop-automation-mcp

Windows 桌面自动化 MCP 服务：截图 → 视觉定位 → 精确点击 一步闭环

让任何 MCP 客户端（Pi / Claude / Cursor...）通过 4 个工具控制 Windows 桌面： 精确点击任何坐标、全屏截图、视觉定位 UI 元素（三阶段校准，±1~5px）、定位+点击一步完成。

零依赖（仅 Node 18+ 内置 API + 可选 sharp），原生解决"注入点击被应用过滤、视觉模型定位不准"两大痛点。 视觉模型通过 config.json / 环境变量 配置，代码内不含任何密钥，可放心上传 GitHub。

---

✨ 4 个工具

工具	功能
desktop_click(x, y, hold_ms?, times?)	鼠标单击指定物理像素坐标（高完整性 + 真人式按压）
desktop_screenshot(path?)	全屏截图，返回 PNG 路径
desktop_locate(target, image_path?, refine?)	视觉定位目标元素，返回物理坐标（三阶段校准）
desktop_click_target(target, image_path?)	定位 + 点击 一步完成

🚀 安装

1. 克隆

git clone https://github.com/loser1727/desktop-automation-mcp
cd desktop-automation-mcp

2. 编译点击工具（可选，仓库已带编译好的 exe）

cd tools
# Windows 自带 .NET Framework csc（或任意 C# 编译器）
C:\Windows\Microsoft.NET\Framework64\v4.0.30319\csc.exe /nologo /target:exe ^
  /out:CursorClick.exe /win32manifest:CursorClick.manifest CursorClick.cs

CursorClick.exe 是自提权程序（manifest requireAdministrator）——点击时自动 UAC 提升 （需系统 ConsentPromptBehaviorAdmin=0 自动批准，或无干扰时手动点"是"）。

3. 确保 sharp 可用（定位裁剪/放大需要）

sharp 一般已随 Pi/其他依赖就绪；若缺，在 server.js 所在目录执行：

npm install sharp

4. 配置视觉模型（关键，见下节）

cp config.example.json config.json   # 然后编辑填入你的 baseUrl / apiKey / model

5. 注册到 MCP（Pi 的 ~/.pi/agent/mcp.json）

{
  "mcpServers": {
    "desktop-automation": {
      "command": "node",
      "args": ["C:\\path\\to\\desktop-automation-mcp\\server.js"]
    }
  }
}

其他 MCP 客户端（Claude Desktop 等）同理放入其 mcp 配置。重启 Pi/客户端生效。

---

⚙️ 视觉模型配置（换模型超简单）

配置优先级：环境变量 > config.json > 内置默认值。config.json 位于 server.js 同目录，已被 .gitignore 忽略（不会泄露密钥）。

方式一：config.json（推荐）—— 支持多模型阶梯式自动切换

{
  "models": [
    {
      "name": "智谱 GLM-4V-Flash (免费, 优先)",
      "baseUrl": "https://open.bigmodel.cn/api/paas/v4",
      "apiKey": "你的智谱密钥",
      "model": "glm-4v-flash",
      "disableThinking": false
    },
    {
      "name": "火山方舟 Doubao (备用)",
      "baseUrl": "https://ark.cn-beijing.volces.com/api/v3",
      "apiKey": "ark-你的密钥",
      "model": "doubao-seed-2-1-turbo-260628",
      "disableThinking": true
    }
  ],
  "maxWidth": 1024,
  "timeoutMs": 90000,
  "retries": 2,
  "maxTokens": 500,
  "disableThinking": true,
  "extraBody": {},
  "fineCropWidth": 320,
  "fineCropHeight": 240,
  "fineZoom": 3,
  "ultraCropWidth": 150,
  "ultraCropHeight": 110,
  "ultraZoom": 6,
  "clickExe": ""
}

阶梯式自动切换：models 数组按顺序尝试——第一个失败（网络/HTTP 错误/超时/空响应）自动切第二个，以此类推；全部失败才报错。启动日志会打印当前阶梯：视觉模型阶梯: A → B → C。

💡 建议把免费模型放最前面（如智谱 GLM-4V-Flash），付费/更强模型作后备——零成本优先，挂了再自动升级。

字段	说明
models	视觉模型阶梯数组（按顺序尝试）。每项可覆盖全局设置：name/baseUrl/apiKey/model/disableThinking/timeoutMs/retries/maxWidth/extraBody
baseUrl	任意 OpenAI 兼容 /chat/completions 端点（豆包 Ark、智谱 GLM、Gemini、MiniMax、OpenAI…）
apiKey	你的密钥（只放这里，绝不进代码）
model	视觉模型 ID —— 换模型只改这一行
maxWidth	粗定位输入图最大宽度（默认 1024；越小越快，精度略降）
disableThinking	true 时发送 {"thinking":{"type":"disabled"}}（豆包等带思考的模型默认思考极慢，必须关；GLM-4V-Flash 等无此参数会忽略）
extraBody	附加请求参数，Object.assign 进请求体 —— 适配任何 API 的特殊参数（如 {"enable_thinking": false}）
fineCropWidth/Height/zoom、ultraCropWidth/Height/zoom	细/超细定位的裁剪尺寸与放大倍数
timeoutMs / retries / maxTokens	单次视觉请求超时、重试次数、最大输出 token
clickExe	自定义点击工具路径（默认 <repo>/tools/CursorClick.exe）

兼容：不写 models 数组时，使用传统单模型字段 baseUrl/apiKey/model（等价于一个元素的阶梯）。

方式二：环境变量

变量	说明
VISION_BASE_URL	视觉 API 网关地址（兼容别名 LITTLEAPI_BASE / ARK_BASE）
VISION_API_KEY	API 密钥（兼容别名 LITTLEAPI_KEY / ARK_API_KEY）
VISION_MODEL	模型 ID（兼容别名 LITTLEAPI_VISION_MODEL / ARK_VISION_MODEL）
VISION_MAX_WIDTH / VISION_QUALITY / VISION_TIMEOUT_MS / VISION_RETRIES / VISION_MAX_TOKENS / VISION_DISABLE_THINKING	对应 config 字段
CLICK_EXE	点击工具路径

兼容性说明：旧的 LITTLEAPI_* / ARK_* 环境变量继续有效，升级无缝。

---

💡 使用示例

A. 定位一个按钮

desktop_locate(target="下载按钮")
→ {"x":1180,"y":341,"method":"ultra(粗→细→超细 6x)"}

B. 定位并点击（一步）

desktop_click_target(target="开始游戏")
→ {"located":{"x":700,"y":400,"method":"ultra..."},"click":{"ok":true}}

C. 先截图再人工检查

desktop_screenshot() → 返回路径 → 任何工具打开查看

🔬 工作原理

定位：三阶段渐进放大 + 十字校准

视觉模型报"绝对像素坐标"不可靠（后端把图缩放进内部网格，无尺子，误差 100px+），但在局部放大图上定位非常准。所以：

① 粗定位：全图 → maxWidth(1024)px → 四角红十字校准 → 仿射变换 → ±50px
② 细定位：320×240 裁剪 3× 放大 → 局部十字校准 → ±10px
③ 超细定位：150×110 裁剪 6× 放大 → ±1~5px ✅

实测误差（合成 UI）：Cancel (341,306) vs (340,305) / Settings (661,181) vs (660,180) = 1px

点击：高完整性真人式点击

CursorClick.exe（自提权 manifest）
→ per-monitor DPI aware（物理像素坐标系，适配 125%/150% 缩放）
→ SetCursorPos 精确定位
→ SendInput DOWN → 保持 120ms（真实按压时长，防止极短按压被 UI 忽略）→ UP

解决了两类常见问题：

• UIPI 权限：普通权限注入点击被管理员级应用（如 Steam）静默丢弃 → 自提权运行
• 注入过滤：Steam 等应用会检测 LLMHF_INJECTED 过滤合成输入 → 保持时长/多阶段重试提高命中

📁 文件结构

desktop-automation-mcp/
├── server.js              ← MCP 服务本体（零依赖）
├── config.example.json    ← 配置模板（含多模型阶梯示例，复制为 config.json 后填写）
├── .gitignore             ← 忽略 config.json / 日志（防密钥泄露）
├── tools/
│   ├── CursorClick.cs     ← 点击工具源码（C#，可编译）
│   ├── CursorClick.manifest ← 自提权清单（requireAdministrator）
│   └── CursorClick.exe    ← 编译好的可执行文件
└── README.md

⚠️ 注意事项

• 坐标 = 物理像素：截图尺寸与点击坐标同源，天然一致；DPI 缩放系统下也可直接使用
• 点击前确保目标窗口在前台（SendInput 投递到前台窗口）
• desktop_click_target 依赖视觉 API 可用；网络不佳时自动重试（可配置）
• 未配置 API Key 时服务仍可启动（截图/点击可用），但定位会报错——请按上文配置

与 pi-vision-locate 扩展的配合

• pi-vision-locate（Pi 扩展）：聊天内直接识图/定位
• 本项目（MCP）：程序化截图/定位/点击闭环

两者可独立使用，也可组合（扩展定位 → MCP 点击）。

📄 License

MIT