桌面- 触摸- mcp
Windows的计算机用MCP服务器. 让 Claude, Cursor 或任何 MCP 客户端看到并操作您的 Windows 10/11 桌面 — 截图、 UI 自动化、 Chrome CDP、 键盘 / 鼠标、 终端 — 与 语义 发现- 此时- 动作瞄准 避免像素坐标猜想 每个行动感知卫士 在它发生之前 捕捉错误的窗口打字.
npx -y @harusame64/desktop-touch-mcp
32个工具,本土Rust引擎 (UIA in 2 ms),零配置的PowerShell倒置,完整的CJK支持,MIT许可. 在您的 Claude / Cursor / VS 代码副驾驶配置中添加上面的片段, Claude 可以驱动 Notepad, Excel, Chrome, Windows 终端, 以及您机器上的任何其他应用程序 .
为什么要用像素点击? 每个工具都有两种想法: 发现当时的动作 —— 说
desktop_discover返回具有短寿命租赁而不是原始坐标的互动实体,所以desktop_act运行于 什麽 你是说,不是 地点 这是... 和 每个行动感知卫士 在输入地之前验证目标窗口的身份和界限,在输入地之前捕获错误的窗口打入和 stale-坐标点击.2.1 国家 通过元素计数而不是深度读取UI自动化:Chrome, Edge和VS代码页面,探索者和设置值,Word的正文被读取并可以被操作,而UIA仍然无法看到的东西和以前一样倒回OCR和Set-of-Marks.
desktop_act也可以输入 Word 的正文,并在询问用户后输入 Windows 终端. 2.0 数据 拒绝采取无法采取的行动,有其理由,而不是报告已采取的行动,并拒绝采取旨在hwnd只到那扇窗户 见 变化。 。 。 .
特征
- 每个行为都报告它做了什么 —— 说
desktop_act答案与变化: 出现或消失的元素, 模式, 焦点动作, 屏幕的再油漆(observation),并与narrate:"rich"改变的价值观和名称。 代理从回复中读取点击的结果,而不是取取另一个截图. 在UIA盲目目标上,它也可以附带一个仅是变化区域(PNG)的PNGroiCapture;默认为明显变化,returnCapture:"never"镇压,"always"(第2条). - * 拒绝无法采取的行为,不按规定报告 ——无法到达字段的输入,被对话框所屏蔽的窗口,被关闭的窗口,另一个虚拟桌面上的窗口:没有发送任何信息,而回复名称为原因和下一步要做什么. 以下列行为为目标:
hwnd永远不要降落在另一个拥有相同所有权的窗口. - 读取深窗(2.1) ——UI自动化读取深度为64和500个元素. Chrome, Edge和VS代码页面,2.0称其被忽略的盲,探索和设置值,而Word的正文被读取并可以被操作(一Chrome页面:387ms = 45 in 186ms).
- * 设定马可视倒置 ——游戏,没有无障碍树的RDP会话和app仍然返回可点击元素:当UIA失明时,
desktop_discover财务报告和审定财务报表screenshot(detail="text")切换到混合非CDP管线 — Rust- power grayscale + bilinear upscale → Windows OCR → 集群 → 有编号徽章的红边框 ([1], (中文(简体) ),[2](......) (中文(简体) ). 两种表述方式重新出现:一种是用于空间取向的巴布亚新几内亚表述方式;另一种是用于空间取向的巴布亚新几内亚表述方式elements[]列表为clickAtcoords——不需要CDP. - QQ 背景输入达不到的类型 — Windows 终端, 其中
desktop_act每次询问用户( 需要带引出功能的 MCP 客户端, 超过 stdio) 和terminal编号 :keyboard检查粘贴前的标签, 和Word的身体, 在Word的注意, 无论它是在前面还是后面. - QQ 密钥锁定器 — 终端自动填充您的 SSH / sudo 密码 ——将证书保存到储物柜自己的安全对话框中一次(用 Windows DPAPI 存储在机器上加密;从未显示给助手),然后运行
ssh编号 :sudo在打开的操纵台中key_locker(action='launch_console')——隐藏提示出现时,密码会自动填入,默认情况下每填入确认提示. 见 密钥锁定器。 。 。 . - rust 原生核 ——UIA桥和图像分接是一出Rust土生土长的活塞(英语:
napi-rs+ 键windows-rs:UIA从一条专用线被叫上"COM"来代替产入"PowerShell",图像diffs使用SSE2 SIMD. 没有附加物,每个功能都会透明地回归到PowerShell. npm 启动器只获取匹配其版本的 GitHub 发布器,并在取出它之前验证了 Windows 运行时的zip. - LLM-内在设计 ——围绕LLMS的思维,而不是人类的点击.
run_macro将多个操作分批成一个API呼叫;diffMode只发送自上一个框架以来变化的窗口。 最小的代币,最小的回程. - 反应感知图 - 登记a
lensId用于窗口或浏览器标签,将其传递给动作工具,并进行守护检查post.perception每次动作后反馈。 减少重复screenshot编号 :desktop_state调用并阻止错误的窗口打字或 stale-coorders 点击. - 完整的 CJK 支持 - 使用Win32
GetWindowTextW对于窗口标题, 避免坚果Js 夹克。 为日文/中文/韩文环境支持的IME绕行输入. - 3级指数减少 —— 说
detail="image"(~443吨) /detail="text"(~100-300吨) /diffMode=true(~160吨). 只在需要看到像素时才发送像素. - 1:1坐标模式 —— 说
dotByDot=true以本地分辨率捕获(WebP). 图像像素=屏幕坐标——不需要比例数学. 与origin+ 键scale转至mouse_click,服务器转换为您使用的coords——去除离相/比例错误. - 浏览器抓取数据减少 —— 说
grayscale=true(~50%大小),dotByDotMaxDimension=1280(自动标出并保留了coord),以及windowTitle + region子 crops 帮助排除了浏览器铬和其他无关像素. 重捕的典型减少:50-70%. - 铬智能倒置 —— 说
detail="text"在Chrome/Edge/Brave自动滑行UIA上(禁止在那里慢跑)并运行Windows OCR.hints.chromiumGuard+ 键hints.ocrFallbackFired标记所走道路. - UIA 元素提取 —— 说
detail="text"返回按钮名称和clickAtor为JSON. Claude可以点击正确的元素,而不会看到截图. - 自动锁定 CLI —— 说
window_dock(action='dock')将任何窗口按到屏幕角, 并始终在上方。 设定DESKTOP_TOUCH_DOCK_TITLE='@parent'在 MCP 启动时自动锁定终端托管 Claude —— 进程- 树上行走器可以找到正确的窗口, 不管标题是什么 . - 紧急停站( 故障) ——把鼠标放入 主显示器左上角 (10px以0,0为单位)500ms可触发紧急停站.
所需资源
| 监督办 | Windows 10 / 11(64位). 苹果硅上macOS 14+:有限预览,仅4个工具 看到了吗 macOS (审查) |
| 节点.js | v20+推荐(测试于v22+)——**开发或运行测试套房, 22.12 |
| 动力壳 | 5.1+ (与 Windows 捆绑在一起) – 仅当 Rust 本地引擎无法使用时用作倒置 |
| . NET 网络 | .NET 10桌面运行时间(x64),用于捆绑的助手:OCR,键锁,并打入后台窗口. 没有它 OCR 和 密钥锁定器 不运行, 背景打入控制台 回到张贴的字符, 它会丢失一个相同的字符运行 |
| 克劳德·CLI | claude 命令必须可用 |
说明: 坚果-js 本地绑定需要视觉 C++ Redistributable. 从 微软 如果尚未安装.
注 (Key Locker): (英语) 证书式帮助键 Locker 使用的是一个未签名的可执行文件, 例如 有些机器 Windows SmartScreen 或反病毒可能显示“未知的出版商”警告 第一次运行。 预计将使用桌面-touch-mcp 并在当地运行的助手船 您可以允许它继续运行。 计划在将来发布代码.
安装
npx -y @harusame64/desktop-touch-mcp
Npm出發器严格通过npm包版本解决运行时间. 对于软件包 X.Y.Z,它只获取 GitHub 释放标记 vX.Y.Z,为您的平台下载拉链(desktop-touch-mcp-windows.zip,或 desktop-touch-mcp-macos-arm64.zip 在苹果硅Mac上,验证其SHA256文摘,然后在下方扩展 %USERPROFILE%\.desktop-touch-mcp (单位:千美元)~/.desktop-touch-mcp (原始内容存档于2018-09-28). on macOS. 经核实的缓存释放在后期运行时被再利用.
设定 DESKTOP_TOUCH_MCP_HOME 以覆盖缓存根目录.
旧版本在服务器启动后被移除,保留了运行中的版本和相机(Windows上每个版本约180 MB). 设定 DESKTOP_TOUCH_MCP_KEEP_RELEASES 保留更多(0 留着吧 正在运行的另一客户端的发布被保存 。 删除旧的 releases/vX.Y.Z 在没有客户端运行的情况下,手动文件夹也是安全的.
在一个共享或CI网络上? 第一个运行读取 GitHub 释放 API 到 找到运行时间拉链。 匿名限制是每个IP60个请求/小时,即 共享公共地址( CI 运行器, 办公室 NAT) 在下载前可以耗尽 甚至开始。 设定
GITHUB_TOKEN(或GH_TOKEN环境和环境 发射机对请求进行认证,将限制提高到5000个请求/小时. 普通的家用连接不需要任何标志.
运行发射装置 从源检出? 源头构建
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 总是先联系,所以仍然可以联系到的网络 重新下载并修复被损坏的安装; 只有网络故障到达 倒置,它从磁盘上开始复制您的版本——没有 重新核查——或者,在从未安装该版本时,更新的老版本 释放完成已核实安装的软件。 非网络的回答 失败( a 404, API 率限制, 完整性不匹配的散列) 仍然停止 开始大声。 离开它,除非一个主机超时 强迫你的手: 设置,您当前版本被损坏的安装被重新使用而不是被使用 修复.两个工作在一起: 倒计时,启动仍然等待 退后前暂停,再低一点
DESKTOP_TOUCH_MCP_FETCH_TIMEOUT_MS若为 你的东道主的预算很紧张 请注意, 下载仍然 抵达,无论速度如何缓慢,从不中断——在到达时的倒数答案 网络已经沉默,而不是仅仅缓慢.
与克洛德·CLI登记
添加为 ~/.claude.json 下级 mcpServers数字 :
{
"mcpServers": {
"desktop-touch": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@harusame64/desktop-touch-mcp"]
}
}
}
无需系统提示 . 命令引用通过 MCP 自动注入 Claude initialize 答复 instructions 字段.
与其他客户端注册( HTTP 模式)
需要 HTTP 端点( GPT 桌面、 VS 代码 Copilot、 Cursor等) 的客户端可以使用内建流式 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构建的一个小子集——其行为可能在发布之间发生变化.
在苹果硅Mac上(macOS 14或后期)相同 npx 命令启动 macOS 服务器,有四个工具: desktop_state, (中文(简体) ), desktop_discover, (中文(简体) ), desktop_act (按下,打开查找器侧边栏条目,替换或附加文本)和 screenshot (一扇窗户). 其他工具只有Windows,没有在macOS上列出.
- 赠款 无障碍 - 和 屏幕记录 用于窗口标题和截图 – 到运行服务器的应用程序(Terminal, iTerm, VS Code, Claude app,.) 在 System Sets QQ隐私和安全. 在最近 macOS 上,可访问面板可以有另一个名称;这些命令直接打开两个面板:
礛 重新启动 MCP 服务器 ——在客户端中重新启动或重新连接,或重新启动运行它的应用程序:已经运行的服务器没有看到新的访问权限。 如果截图在允许屏幕录制后仍然失败,则退出并重新打开该应用. 在那之前,工具会回答open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility" open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"PermissionRequired并说什么是给予. - 安装方式
npx仅:带有浏览器下载的放行zip被Gatelayer拒绝(原生模块没有公证). - 仅限stdio(
--http尚未提供). 不支持英特尔·麦克斯和Linux.
工具(32个优化工具)
📖 充分参考数字 :
docs/system-overview.md——关于参数的精通指南,还原计划,协调数学.
• 世界图V2(初级路径)
| 工具 | 说明 |
|---|---|
desktop_discover | 观察桌面. 以租赁方式返回互动实体(UIA、CDP、终端、Visual SoM). |
desktop_act | 通过租赁验证对实体执行动作(单击、输入、设定一个值、选择)。 返回语义 diffs - 加上一个可选 roiCapture (已改变区域 PNG + 下个目标预览) 关于可视化目标. |
观测状态
| 工具 | 说明 |
|---|---|
desktop_state | 轻量级检查焦点,活性窗口,光标,以及自动接受关注信号. |
screenshot | 多模式抓取 : detail='text' (律师事务所/律师事务所), diffMode (P-框架), dotByDot (1:1),以及 background返回廉价 screenshot://by-ref/{id} 链接到保存的图像,而不是每次内置像素. |
screenshot_query 编号 : screenshot_gc | 查看和浏览 disk 截图缓存 : screenshot_query 列出不重读像素而保存的捕获; screenshot_gc 通过保留策略(默认运行后干燥)恢复空间. |
workspace_snapshot | 即时会话取向:一个呼叫中所有窗口缩略图+UI摘要. |
server_status | 本地引擎健康和特性活化的诊断检查,哪个版本回答(version) (中文(简体) ). |
输入控件
| 工具 | 说明 |
|---|---|
keyboard | 发送键盘输入 。 支持背景输入(WM CHAR)和IME安全剪贴板绕行. |
mouse_click 编号 : mouse_drag | 基于精确协调的与跟踪和以力量为重点的保护的互动. |
scroll | 多战略: raw (结节), to_element, (中文(简体) ), smart (虚拟清单),以及 capture (st. |
click_element | 基于UIA的后遗症点击名称/ID(当没有实体时返回). |
QQ 浏览器 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-like 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' 打开自动填充功能控制台(返回 a) paneId 要驱动 ssh编号 :sudo 进入通过 terminal(三); save 编号 : list 编号 : forget 编号 : set_policy 编号 : status 管理约束; fill_once 请求您一次输入密码到一个快速自动填充中不会处理( 无保存; 带有 tag 它保存在窗格的内存中,直到窗格关闭,然后填充只要求填充/取消。 自动填充和 fill_once 只有打开的控制台工作 launch_console启用 DESKTOP_TOUCH_DISABLE_KEY_LOCKER=1。 。 。 . |
办公室(外卖)
| 工具 | 说明 |
|---|---|
excel | 作者并通过COM运行Excel VBA宏. action='run_vba' 将宏写入管理下的托管位置并运行; action='check_access_vbom' 是一个只读的飞行前。 运行无法使用公式工具的 VBA 。 一次性设置 : node scripts/enable-access-vbom.mjs。 。 。 . |
标准工作流程(v1.0.0)
V2 世界- 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
对每次拒绝的追偿提示以及租约的到期: 指南-追回提示和租赁。 。 。 .
更多在指南中
细节存在于 指南数字 :
- 回收提示和租赁
- 终端命令完成( E)
until(中文(简体) ) - 密钥锁定器( 最终证书自动填充)
- 浏览器 CDP 自动化
- 启动时自动锁定 CLI
- 鼠标旋转校正
screenshot关键参数- 警卫
- 鼠标移动速度
- 力量焦点( 插入)
- 自动守护
- 诊断日志
- 高级响应选项
- 本地发动机的性能(在v.0.15计量)
- UI 操作层( V2)
- 参考成本
已知的限制
| 限制 | 细节 | 工作周边 |
|---|---|---|
| 游戏/ 视频播放器可能返回黑色或在 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 调用间接费用 | ~2 ms(焦)/~100 ms(树木)通过Rust本土引擎;~300 ms通过PowerShell倒置 | (一) 涡轮发动机自动装载; workspace_snapshot 内部使用 2 s 超时 |
screenshot(detail='text') 返回 Chrome / WinUI3 上很少的 UIA 元素 | 读取在铬上保持浅度desktop_discover 阅读自2.1起的页控件 | screenshot(detail='text') 自动检测铬并返回到 Windows OCR(hints.chromiumGuard=true) (中文(简体) ). 使用 desktop_discover 用于页面控件,或 browser_open + 键 browser_locate dOM 访问 |
重写网站时chromium 标题- regex 缺失 document.title | 警卫依靠 - Google Chrome 后缀存在; 有网站将其从长标题的末尾推出 | 标题作为平原Chrome(UIA跑道)处理. OCR 路径仍然可以通过 ocrFallback='always' 或当UIA返回时 <5 要素uiaSparse(中文(简体) ) |
browser_* CDP 工具需要使用 Chrome 启动 --remote-debugging-port | 如果Chrome已经运行在默认配置文件上,没有旗帜, browser_open 失败。 CDP E2E套房(tests/e2e/browser-cdp.test.ts)也会在那种状态下失败 | 先关上Chrome,然后 browser_open({launch:{}}) 以调试模式重新启动,或手动启动 Chrome --remote-debugging-port=9222 --user-data-dir=C:\tmp\cdp |
| 层缓冲 TTL | 90后自动清除 ~ 下一个 diffMode 成为I-框架 | 等了很久,打个电话 workspace_snapshot 以明确重置缓冲器 |
keyboard(action='type') 编号 : keyboard(action='press') 跟踪焦点 | 何时 window_dock(action='dock')(pin=true) 在顶部保留另一个窗口(如克洛德 CLI),键盘被该窗口所吸收 | 打电话 focus_window(title=...) 首先核实 isActive=true 通过 screenshot(detail='meta') 发送密钥前 |
keyboard(action='type') em-dash / 在 Chrome/ Edge 中的智能引用 | 非 ASCII 标注 —时 –,聪明引用 "" '')可以作为键盘加速器被截取,将焦点转移到地址栏 | 总是使用 use_clipboard=true 当文字包含这些字符时 |
browser_eval(action='js') 在 React / Vue / Svelte 输入上 | 设置 element.value = ... 或发送合成事件 不更新框架的内部状态 | 使用 browser_fill(selector, value) 它使用本地原型设置器 + 输入Event , 它确实更新 React/Vue/Svelte 状态 |
谢谢
感谢所有尝试过桌面自定义 MCP 服务器, 提交问题的人, 打开公关, 分享什么打破。 每一份bug报告都让下一次发布更精彩. 谢谢你跟我一起建楼!
许可证
麻省理工学院