desktop-touch-mcp

desktop-touch-mcp

日本語

适用于 Windows 的计算机操作 MCP 服务。 让 Claude、Cursor 或任何 MCP 客户端查看并操作你的 Windows 10/11 桌面——截图、UI Automation、Chrome CDP、键盘 / 鼠标、终端——通过先发现再操作的语义定位避免猜测像素坐标，并使用逐操作感知防护在错误窗口输入发生前及时拦截。

npx -y @harusame64/desktop-touch-mcp

包含 32 个工具、原生 Rust 引擎（UIA 耗时 2 ms）、零配置 PowerShell 后备方案，以及完整的 CJK 支持；采用 MIT 许可。将上方代码片段添加到 Claude / Cursor / VS Code Copilot 配置中，Claude 就能操作你机器上的记事本、Excel、Chrome、Windows Terminal 和其他任何应用。

为什么不使用像素点击？ 每个工具都贯穿着两个理念：先发现再操作——desktop_discover 返回带有短期有效租约的交互实体，而非原始坐标，因此 desktop_act 操作的是你指的对象，而不是它所在的位置；以及逐操作感知防护，它会在输入生效前验证目标窗口的身份和边界，在错误窗口输入和过期坐标点击发生前及时拦截。

2.1 按元素数量而非深度读取 UI Automation：Chrome、Edge 和 VS Code 页面，Explorer 和 Settings 的值，以及 Word 正文都可以读取和操作；UIA 仍无法查看的内容则像以前一样回退到 OCR 和 Set-of-Marks。desktop_act 也可以向 Word 正文输入内容，并在征求用户同意后向 Windows Terminal 输入内容。2.0 会拒绝无法执行的操作并说明原因，而不是谎称已完成；通过 hwnd 指定的操作只会触达对应窗口。参见 CHANGELOG。

---

功能

• 🔁 每个操作都会报告执行结果 — desktop_act 会说明发生了哪些变化：出现或消失的元素、模态对话框、焦点移动、屏幕重绘（observation），以及使用 narrate:"rich" 时发生变化的值和名称。Agent 可以直接从回复中读取点击结果，而不必再截一次屏。对于 UIA 无法识别的目标，它还可以附上仅包含变化区域的 PNG（roiCapture；默认在出现可见变化时启用，使用 returnCapture:"never" 可关闭，使用 "always" 可强制启用）。
• 🛑 无法执行的操作会被拒绝，而不会谎报成功 — 如果输入无法到达目标字段、窗口被对话框挡住、窗口已关闭，或窗口位于另一个虚拟桌面上，则不会发送任何内容，回复会说明原因和下一步操作。通过 hwnd 指定的操作绝不会误发到另一个同名窗口。
• 🌐 深度读取窗口（2.1） — UI Automation 的读取深度可达 64 层、500 个元素。2.0 无法读取的 Chrome、Edge 和 VS Code 页面、此前遗漏的资源管理器和设置中的值，以及 Word 正文，现在都可以读取并执行操作（Chrome 页面：387 ms 内读取 6 个元素 → 186 ms 内读取 45 个元素）。
• 🎯 标记集（SoM）视觉回退方案 — 对于游戏、RDP 会话和没有辅助功能树的应用，仍可返回可点击元素：当 UIA 无法识别时，desktop_discover 和 screenshot(detail="text") 会切换到 Hybrid Non-CDP 流程 — 由 Rust 驱动的灰度处理和双线性放大 → Windows OCR → 聚类 → 带编号徽标（[1]、[2]……）的红色边界框。最终会返回两种表示：用于空间定位的 PNG，以及包含 clickAt 坐标的 elements[] 列表 — 无需 CDP。
• ⌨️ 在后台输入无法到达的位置输入文本 — Windows Terminal 中，每次操作前都会询问用户（需要支持询问功能、通过 stdio 连接的 MCP 客户端）；也支持在 Word 正文中输入，无论 Word 位于前台还是后台，都会在 Word 的插入点输入。
• 🔐 Key Locker — 终端自动填入 SSH / sudo 密码 — 只需将凭据保存一次到 Key Locker 自带的安全对话框中（使用 Windows DPAPI 加密后存储在本机，绝不会向助手显示），然后在通过 key_locker(action='launch_console') 打开的控制台中运行 ssh / sudo — 出现隐藏的密码提示时会自动填入密码，默认情况下每次填入前都会要求确认。请参阅 Key Locker。
• ⚡ Rust 原生核心 — UIA 桥接和图像差异比较由 Rust 原生插件实现（napi-rs + windows-rs）：UIA 通过专用线程调用 COM，而非启动 PowerShell；图像差异比较使用 SSE2 SIMD。没有该插件时，所有函数都会透明地回退到 PowerShell。npm 启动器只会下载与自身版本匹配的 GitHub Release，并在解压前验证 Windows 运行时 ZIP。
• LLM 原生设计 — 围绕大模型的思维方式构建，而非人类的点击习惯。run_macro 可将多个操作合并为一次 API 调用；diffMode 只发送自上一帧以来发生变化的窗口。令牌用量更少，往返次数更少。
• 响应式感知图 — 为窗口或浏览器标签页注册 lensId，将其传递给操作工具，即可在每次操作后获得经过防护校验的 post.perception 反馈。它可以减少重复调用 screenshot / desktop_state，并防止在错误窗口中输入或使用过期坐标点击。
• 全面支持 CJK — 使用 Win32 GetWindowTextW 获取窗口标题，避免 nut-js 产生乱码。支持日语、中文和韩语环境下绕过 IME 输入。
• 3 级令牌用量缩减 — detail="image"（约 443 个令牌）/ detail="text"（约 100–300 个令牌）/ diffMode=true（约 160 个令牌）。只有确实需要查看时才发送像素数据。
• 1:1 坐标模式 — dotByDot=true 可按原生分辨率捕获画面（WebP）。图像像素 = 屏幕坐标 — 无需换算比例。将 origin+scale 传递给 mouse_click 后，服务会替你转换坐标 — 避免坐标偏差和缩放错误。
• 减少浏览器捕获数据 — grayscale=true（约减少 50% 文件大小）、dotByDotMaxDimension=1280（自动缩放并保留坐标），以及 windowTitle + region 局部裁剪，都有助于排除浏览器界面和其他无关像素。大型捕获通常可减少 50–70% 的数据。
• Chromium 智能回退 — 对 Chrome/Edge/Brave 使用 detail="text" 时，会自动跳过 UIA（因为速度慢得难以接受），改为运行 Windows OCR。hints.chromiumGuard + hints.ocrFallbackFired 会标明所采用的流程。
• UIA 元素提取 — detail="text" 会以 JSON 形式返回按钮名称和 clickAt 坐标。Claude 无需查看截图，就能点击正确的元素。
• CLI 自动贴靠屏幕边缘 — window_dock(action='dock') 会将任意窗口贴靠到屏幕角落并设为始终置顶。设置 DESKTOP_TOUCH_DOCK_TITLE='@parent'，即可在 MCP 启动时自动将托管 Claude 的终端贴靠到屏幕边缘 — 进程树遍历器无论窗口标题为何，都能找到正确的窗口。
• 紧急停止（安全开关） — 将鼠标停在主显示器左上角（距 0,0 不超过 10px）500 ms，即可触发紧急停止。

---

要求

OS	Windows 10 / 11（64 位）。Apple Silicon 上的 macOS 14+：有限预览版，仅支持 4 个工具 — 请参阅 macOS（预览版）
Node.js	推荐使用 v20+（已在 v22+ 上测试）— **开发或运行测试套件需要 `^22.12
PowerShell	5.1+（Windows 附带）— 仅在 Rust 原生引擎不可用时用作备用方案
Claude CLI	必须能够使用 claude 命令

注意： nut-js 原生绑定需要 Visual C++ Redistributable。 如果尚未安装，请从 Microsoft 下载。

注意（Key Locker）： Key Locker 使用的凭据助手是未经签名的可执行文件，因此在 部分计算机上，Windows SmartScreen 或杀毒软件可能会在首次运行时显示“未知发布者”警告。 这是预期行为 — 此助手随 desktop-touch-mcp 一同提供，并在本机上运行；你可以允许它继续运行。计划在未来版本中进行代码签名。

---

安装

npx -y @harusame64/desktop-touch-mcp

npm 启动器严格根据 npm 包版本解析运行时。对于包 X.Y.Z，它只会获取 GitHub Release 标签 vX.Y.Z，下载适用于你平台的 zip 文件（Windows 上为 desktop-touch-mcp-windows.zip，Apple Silicon Mac 上为 desktop-touch-mcp-macos-arm64.zip），验证其 SHA256 摘要，然后才将其解压到 %USERPROFILE%\.desktop-touch-mcp（macOS 上为 ~/.desktop-touch-mcp）。后续运行时会复用已验证的缓存版本。

设置 DESKTOP_TOUCH_MCP_HOME 可覆盖缓存根目录。

服务启动后会移除旧版本，只保留正在运行的版本和另一个版本（每个 Windows 版本约 180 MB）。设置 DESKTOP_TOUCH_MCP_KEEP_RELEASES 可保留更多版本（0 表示全部保留）。其他客户端正在运行的版本会予以保留。只要没有客户端正在运行，手动删除旧的 releases/vX.Y.Z 文件夹也不会有问题。

使用共享网络或 CI 网络？ 首次运行时会读取 GitHub Releases API 来查找运行时 zip 文件。匿名请求的限制为每个 IP 每小时 60 次，共享的公共 地址（CI 运行器、办公室 NAT）可能会在开始下载前就用完额度。在环境中设置 GITHUB_TOKEN（或 GH_TOKEN），启动器就会通过身份验证发起请求，将限制提高到每小时 5,000 次。普通家庭网络无需令牌。

从源代码检出目录运行启动器？ 源代码构建中的 bin/launcher.js 使用占位完整性哈希（sha256: "PENDING"），而不是最终的哈希值。 为避免下载并运行未经验证的运行时，启动器会默认拒绝运行——此保护机制可避免意外发布或 尚未完成的启动器悄然运行未经验证的代码。已发布的 npm 版本始终包含真实的 SHA256，因此最终用户不会遇到此情况。如果你确实要从源代码运行 启动器，请设置 DESKTOP_TOUCH_MCP_ALLOW_UNVERIFIED=1 跳过完整性验证 （仅限开发）。

宿主是否会在启动器完成前就放弃？ 有些桌面宿主会给插件固定的就绪时间—— 60 秒很常见；如果启动器一直等不到 GitHub 的响应，就可能耗尽全部时间。以下两个环境变量 可应对此情况。

DESKTOP_TOUCH_MCP_FETCH_TIMEOUT_MS（默认值为 15000）限制启动器在没有收到 GitHub 响应的情况下等待的时间。此限制适用于版本查询和下载；对于下载，它计算的是无响应时长，而不是总 耗时，因此较大的运行时仍可通过慢速连接安装。若值不是正的毫秒数，系统会忽略该值并发出警告。

DESKTOP_TOUCH_MCP_OFFLINE_FALLBACK=1 可让启动器在完全无法连接 GitHub 时，启动 已安装的版本。默认关闭。启动器始终会先联系 GitHub，因此网络可用时仍会重新下载并修复损坏的安装； 只有发生网络故障时才会使用回退机制：启动磁盘上当前版本的副本（不再重新验证），或者如果当前版本从未安装过，则启动最近一个已完成验证安装的旧版本。非网络故障的响应（404、API 速率限制、完整性哈希不匹配）仍会阻止启动并明确报错。除非宿主超时迫使你启用此选项，否则请保持关闭：启用期间，当前版本的损坏安装会被直接复用，而不是修复。

两个选项可以配合使用：启用回退后，启动仍会等待超时后才回退；因此，如果宿主的时间预算较紧，请调低 DESKTOP_TOUCH_MCP_FETCH_TIMEOUT_MS。另请注意，只要下载仍在进行，无论速度多慢，都不会中断——只有网络完全没有响应时才会触发回退，而不是网络速度较慢时。

使用 Claude CLI 注册

在 ~/.claude.json 的 mcpServers 下添加：

{
  "mcpServers": {
    "desktop-touch": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@harusame64/desktop-touch-mcp"]
    }
  }
}

无需系统提示词。 命令参考会通过 MCP initialize 响应的 instructions 字段自动注入 Claude。

在其他客户端中注册（HTTP 模式）

需要 HTTP 端点的客户端（GPT Desktop、VS Code Copilot、Cursor 等）可使用内置的 Streamable HTTP 传输：

npx -y @harusame64/desktop-touch-mcp --http
# or with a custom port:
npx -y @harusame64/desktop-touch-mcp --http --port 8080

服务会在 http://127.0.0.1:23847/mcp 启动（仅限本地主机）。在 MCP 客户端设置中注册此 URL。可通过 http://127.0.0.1:<port>/health 进行健康检查。

在 HTTP 模式下，系统托盘图标会显示当前活动 URL，并提供快速复制和在浏览器中打开的快捷操作。

开发环境安装

git clone https://github.com/Harusame64/desktop-touch-mcp.git
cd desktop-touch-mcp
npm install

安装后构建：

npm run build

对于本地检出，可直接注册构建好的服务：

{
  "mcpServers": {
    "desktop-touch": {
      "type": "stdio",
      "command": "node",
      "args": ["D:/path/to/desktop-touch-mcp/dist/index.js"]
    }
  }
}

注意： 将 D:/path/to/desktop-touch-mcp 替换为克隆此仓库的实际路径。

macOS（预览版）

有限预览。 macOS 版本仅包含 4 个工具，是 Windows 版本的一小部分，并且其行为可能随版本发布而变化。

在 Apple Silicon Mac（macOS 14 或更高版本）上，同一条 npx 命令会启动包含四个工具的 macOS 服务：desktop_state、desktop_discover、desktop_act（按下、替换或追加文本）和 screenshot（单个窗口）。其他工具仅适用于 Windows，不会在 macOS 上列出。

• 在“系统设置”›“隐私与安全性”中，向运行服务的应用（Terminal、iTerm、VS Code、Claude 应用等）授予辅助功能权限；若要读取窗口标题和截取屏幕截图，还需授予屏幕录制权限。在较新的 macOS 版本中，“辅助功能”面板可能使用其他名称；运行以下命令可直接打开这两个面板：

  open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"
  open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"
  

  然后重启 MCP 服务——在客户端中重启或重新连接，或者重启运行服务的应用：已在运行的服务无法检测到新授予的辅助功能权限。如果授予屏幕录制权限后仍无法截取屏幕截图，请退出并重新打开该应用。在此之前，这些工具会返回 PermissionRequired，并说明需要授予的权限。
• 仅通过 npx 安装：通过浏览器下载的发行版 zip 会被 Gatekeeper 拒绝（原生模块未经公证）。
• 仅支持 stdio（暂不支持 --http）。不支持 Intel Mac 和 Linux。

---

工具（32 个优化工具）

📖 完整参考：docs/system-overview.md — 参数、返回架构和坐标计算的详尽指南。

🌐 World-Graph V2（主要路径）

工具	描述
desktop_discover	观察桌面。返回带有租约的交互实体（UIA、CDP、Terminal、Visual SoM）。
desktop_act	通过租约验证对实体执行操作（点击、输入、设置值、选择）。返回语义差异；对于仅支持视觉的目标，还可选择返回 roiCapture（已更改区域的 PNG + 下一个目标预览）。

👁️ 观察与状态

工具	描述
desktop_state	轻量检查焦点、活动窗口、光标和 Auto-Perception 注意力信号。
screenshot	多模式截图：detail='text'（UIA/OCR）、diffMode（P 帧）、dotByDot（1:1）和 background。返回指向已保存图像的轻量 screenshot://by-ref/{id} 链接，而非每次都内嵌像素。
screenshot_query / screenshot_gc	检查和清理由引用链接指向的磁盘截图缓存：screenshot_query 会列出已保存的截图，而不重新读取像素；screenshot_gc 会按保留策略回收空间（默认先试运行）。
workspace_snapshot	即时了解会话状态：一次调用即可获取所有窗口缩略图和 UI 摘要。
server_status	诊断原生引擎运行状况和功能启用状态。

⌨️ 输入与控制

工具	描述
keyboard	发送键盘输入。支持后台输入（WM_CHAR）和兼容 IME 的剪贴板绕过方式。
mouse_click / mouse_drag	基于精确坐标进行交互，并提供归位和强制焦点保护。
scroll	多种策略：raw（刻度）、to_element、smart（虚拟列表）和 capture（拼接）。
click_element	通过名称/ID 执行传统的基于 UIA 的点击（实体不可用时的备用方案）。

🌐 浏览器 CDP（Chrome/Edge/Brave）

工具	描述
browser_open / browser_navigate	以幂等方式启动调试模式，并可靠地进行导航。
browser_click / browser_fill / browser_form	高级 DOM 交互，可在重绘和框架重新渲染期间保持稳定。
browser_eval	通过 js（脚本）、dom（HTML）和 appState（SPA 数据提取）进行深度检查。
browser_overview / browser_search / browser_locate	语义发现、类似 grep 的 DOM 搜索，以及像素级精准的坐标查找。

🛠️ 实用工具与工作流

工具	描述
terminal	统一的命令执行：run（发送 + 等待 + 读取）、read（OCR/UIA）和 send。run 的完成模式：quiet、pattern 和 exit（等待命令完成并返回其退出代码 — 参见终端命令完成）。
wait_until	在服务端高效轮询窗口、焦点、文本或 URL 状态变化。
window_dock / focus_window	窗口管理：pin（始终置顶）、unpin、dock（吸附到角落）和 focus。
workspace_launch	启动应用并自动检测新的 HWND（支持本地化标题）。
run_macro	将最多 50 项操作批量合并为一次往返，以获得最高效率。
clipboard / notification_show	系统级文本交换和用户提醒。
key_locker	管理由终端代为自动填入的凭据（SSH 密钥口令、sudo / 登录密码）。机密信息只需在保管库自己的安全对话框中输入一次，并以加密形式存储在此计算机上（Windows DPAPI）；助手绝不会看到这些信息。action='launch_console' 会打开支持自动填充的控制台（返回一个 paneId，供 terminal 用于执行 ssh / sudo）；save / list / forget / set_policy / status 用于管理绑定；fill_once 会要求你在自动填充无法处理的提示中输入一次密码（不会保存）。自动填充和 fill_once 仅适用于通过 launch_console 打开的控制台。使用 DESKTOP_TOUCH_DISABLE_KEY_LOCKER=1 禁用。

📊 Office（Excel）

工具	描述
excel	通过 COM 编写并运行 Excel VBA 宏。action='run_vba' 会将宏写入受管理的 Trusted Location 并运行；action='check_access_vbom' 是只读的预检。可在仅支持公式的工具无法处理时运行 VBA。一次性设置：node scripts/enable-access-vbom.mjs。

---

标准工作流（v1.0.0）

推荐使用 v2 World-Graph 接口（desktop_discover / desktop_act）作为调度路径。对于原生应用、浏览器和终端，四次调用的流程完全相同。

desktop_state          → orient: focused window/element, modal, attention signal
desktop_discover       → find actionable entities (returns lease + windows[])
desktop_act(lease, …)  → act on entity (returns attention + post.perception)
desktop_state          → confirm the world changed as expected

点击 — 优先级顺序：

browser_click(selector)               → Chrome / Edge (CDP, stable across repaints)
desktop_act(lease, action='click')    → native / dialog / visual (entity-based; use after desktop_discover)
click_element(name | automationId)    → native UIA fallback if desktop_act returns ok:false (not for list/tree/grid items)
mouse_click(x, y, origin?, scale?)    → pixel last resort; origin+scale from dotByDot screenshots only

每种拒绝情况的恢复提示，以及租约的到期方式：指南 → 恢复提示和租约。

---

指南中的更多内容

详情请参阅指南：

• 恢复提示与租约
• 终端命令补全（until）
• 密钥保管器（终端凭据自动填充）
• 浏览器 CDP 自动化
• 启动时自动停靠 CLI
• 鼠标归位校正
• screenshot 的关键参数
• 安全
• 鼠标移动速度
• 强制聚焦（AttachThreadInput）
• 自动防护
• 诊断日志
• 高级响应选项
• 原生引擎性能（在 v0.15 测量）
• UI 操作层（V2）
• Token 成本参考

---

已知限制

限制	详情	解决方法
游戏 / 视频播放器可能在 PrintWindow 捕获时返回黑屏或卡住	DirectX 全屏应用可能无法在 PW_RENDERFULLCONTENT 下重绘。以窗口为目标的 screenshot(detail='image') 在 PrintWindow 未返回数据或返回全黑且方差为零的帧时，已会自动回退到 BitBlt；但导致调用卡住的 DirectX 表面不会触发回退。	使用 screenshot({mode:'background', fullContent:false}) 重试，以切换到旧版 PrintWindow 标志；如果仍是黑屏，BitBlt 回退路径（默认 mode='normal'）至少会返回屏幕上可见的矩形区域——hints.captureFallbackReason 会显示 printwindow-all-black
UIA 调用开销	通过 Rust 原生引擎约为 2 毫秒（焦点）/100 毫秒（树）；通过 PowerShell 回退约为 300 毫秒	Rust 引擎会自动加载；workspace_snapshot 内部使用 2 秒超时
screenshot(detail='text') 在 Chrome / WinUI3 上返回的 UIA 元素较少	在 Chromium 上，该读取仍停留在浅层（自 2.1 起，desktop_discover 会读取页面控件）	screenshot(detail='text') 会自动检测 Chromium 并回退到 Windows OCR（hints.chromiumGuard=true）。页面控件请使用 desktop_discover，或使用 browser_open + browser_locate 访问 DOM
网站重写 document.title 时，Chromium 标题正则匹配会失败	守卫逻辑依赖 - Google Chrome 后缀；有些网站会在标题过长时将其挤到末尾之外	标题会被视为普通 Chrome 标题（运行 UIA）。仍可通过 ocrFallback='always'，或在 UIA 返回的元素少于 5 个（uiaSparse）时使用 OCR 路径
browser_* CDP 工具需要在启动 Chrome 时使用 --remote-debugging-port	如果 Chrome 已在默认配置文件下运行但未带该标志，browser_open 会失败。CDP E2E 测试套件（tests/e2e/browser-cdp.test.ts）在这种情况下也会失败	先关闭 Chrome，然后 browser_open({launch:{}}) 会以调试模式重新启动它；或者手动使用 --remote-debugging-port=9222 --user-data-dir=C:\tmp\cdp 启动 Chrome
图层缓冲区 TTL	缓冲区在闲置 90 秒后会自动清除 → 下一个 diffMode 会变为 I 帧	长时间等待后，调用 workspace_snapshot 以显式重置缓冲区
keyboard(action='type') / keyboard(action='press') 会跟随焦点	当 window_dock(action='dock')(pin=true) 让另一个窗口保持在顶层时（例如 Claude CLI），按键可能会被该窗口接收	先调用 focus_window(title=...)，并在发送按键前通过 screenshot(detail='meta') 确认 isActive=true
Chrome / Edge 中 keyboard(action='type') 输入长破折号 / 智能引号	非 ASCII 标点（长破折号 —、短破折号 –、智能引号 "" ''）可能会被拦截为键盘快捷键，从而使焦点转移到地址栏	文本包含此类字符时，务必使用 use_clipboard=true
React / Vue / Svelte 输入框中的 browser_eval(action='js')	设置 element.value = ... 或派发合成事件不会更新框架的内部状态	使用 browser_fill(selector, value)——它使用原生原型 setter 和 InputEvent，可以更新 React/Vue/Svelte 状态

---

致谢

非常感谢所有尝试过桌面自动化 MCP 服务、提交问题、发起 PR 并分享故障情况的人。 每一份错误报告都让下一个版本变得更好。 感谢你与我一同构建！

---

许可证

MIT