Realhands — Real Desktop Computer Use

computer-use-mcp（“realhands”）

一个让 Claude 像人类一样操作你的真实电脑 的 MCP 服务——移动实际鼠标、点击、输入文字，并读取实际屏幕。

与 OpenAI Operator、browser-use 或 Playwright Agent（它们会启动独立、隔离且未登录的 Chrome）不同，这个服务驱动的是物理操作系统的光标和键盘。因此，它可以在你自己的 Chrome 和已登录会话中运行，也可以在其他任何应用中运行——因为在任何网站看来，操作它的都只是一个坐在键盘前的人。

状态：已上线并经过实战验证。 已在 Claude Code 中注册为用户级 MCP，名称为 realhands（工具 mcp__realhands__computer），并自 2026-06-02 起显示为 ✓Connected。 2026-06-09，它通过用户真实且已登录的 Chrome，端到端完成了一次 Google Play Console 部署（上传应用、填写版本说明、提交）。

该服务注册为 realhands，而非 computer-use，因为 Claude Code 已保留 “computer-use”这一名称。

工作原理

Claude（Desktop 或 Code）负责运行 Agent 循环。你输入任务后，Claude 会在“观察 → 思考 → 执行”循环中调用唯一的 computer 工具：

观察 — screenshot 返回真实屏幕（缩小至约 1280px，以提高定位准确性） → 思考 — Claude 选择下一步操作和像素坐标 → 执行 — 服务移动真实鼠标／在真实键盘上输入文字 → 每次操作后都会自动返回一张新截图，然后循环继续。

两个 Windows 专属细节可确保点击准确命中（src/screen.py）：

• DPI 感知 — 导入时会设置 SetProcessDpiAwareness(2)，确保即使在显示缩放（125% / 150% / …）下，截图像素也与 pyautogui 光标坐标一致。
• 无状态坐标缩放 — 发送前，截图会使用 LANCZOS 缩小，使最长边不超过 COMPUTER_USE_MAX_DIM；传入的点击坐标会按比例还原为实际像素。缩放比例仅由显示器 几何信息和 MAX_DIM 决定，因此坐标映射不会依赖上一张截图。坐标会限制在目标显示器范围内，避免意外点击落到屏幕之外。 每个轴都会向下舍入到 28px 的整数倍视觉图块，因此两个轴的缩放比例可能略有不同（<2.2%）；to_real() 会分别使用各自的比例进行映射，确保准确无误。

多显示器： 每次调用都可选择传入 monitor 索引（1 = 主显示器，2.. = 其他显示器，0 = 整个虚拟桌面）。action="monitors" 会列出当前配置。 位于主显示器左侧或上方的屏幕，原点可能为负值——to_real() 会处理偏移量。点击时，必须使用与所点击截图相同的显示器。

架构

src/realhands/
  server.py   FastMCP server "computer-use"; the single `computer` tool (action enum
              modeled on Anthropic's reference computer_20250124 tool); runs one
              action or a batch of `steps`, then returns status text + at most one
              screenshot
  screen.py   DPI awareness, mss capture, patch-aligned downscale, model-space ->
              real-pixel mapping, unchanged-screen detection
  input.py    pyautogui mouse/keyboard execution; xdotool-style key-name translation
              (Return, Page_Down, ctrl+a, super, ...); clipboard-paste fast path for
              long/Unicode/multiline typing (preserves your existing clipboard);
              activate_window via win32 AttachThreadInput
  safety.py   kill switches + lazy arm / stand-down lifecycle
  config.py   .env-driven configuration (all defaults are sensible; .env is optional)
install.py    one-shot installer: venv, deps, .env, Claude Desktop registration

技术栈：Python 3.10/3.11 · mcp（FastMCP、stdio）· pyautogui · mss · pillow · pynput · keyboard · pyperclip · python-dotenv，以及用于 activate_window 的 pygetwindow 和 pywin32。

computer 工具

一个带有 action 参数的工具：

操作	功能
screenshot	截取屏幕（开始任务时始终先执行此操作）
cursor_position	报告鼠标的实际位置
monitors	列出检测到的显示器（适用于多屏设置）
mouse_move	将光标平滑移动到 coordinate
left_click / right_click / middle_click / double_click / triple_click	在 coordinate（或当前位置）单击
left_click_drag	从 text="x1,y1" 拖动到 coordinate=[x2,y2]
left_mouse_down / left_mouse_up	按下 / 释放鼠标左键
scroll	在 coordinate 处滚动（按 scroll_direction 方向滚动 scroll_amount 格）
type	输入 text（长文本、Unicode 或多行文本使用剪贴板粘贴）
key	按下某个按键或组合键 — "Return"、"ctrl+s"、"alt+Tab"
hold_key	按住按键 duration 秒
activate_window	按标题子串将应用置于前台（可绕过 Windows 的前台锁定；比点击任务栏可靠得多）
wait	等待 duration 秒，然后截屏
stop	停止操作：关闭 STOP 覆盖层并释放紧急热键（作为最后一个操作调用）

坐标以最近一次截图的像素空间为准；每次截屏时都会报告截图尺寸。每次非截屏操作后，工具会等待约 0.4 秒，让界面稳定下来，然后返回一张新截图。

节省令牌

截屏是驱动桌面时的主要成本，而且不只产生一次：每张图像都会留在对话中，并在之后的每一轮作为历史记录重新发送。Claude 按 28×28 像素块计费视觉输入 — tokens = ⌈w/28⌉ × ⌈h/28⌉ — 因此此服务采取四种方式来降低费用。

批量执行步骤。 传入 steps（一个操作字典列表），而不是每个操作单独调用一次，这样整个运行过程结束时只会生成一张截图：

{"steps": [{"action": "left_click", "coordinate": [420, 300]},
           {"action": "type",  "text": "[email protected]"},
           {"action": "key",   "text": "Tab"},
           {"action": "type",  "text": "secret"},
           {"action": "key",   "text": "Return"}]}

这样只需 1 125 个视觉令牌，而不是 5 625 个，往返次数也从五次降为一次 — 后者节省更多，因为每省下一轮，就能避免重新发送整份对话记录。如果某一步失败，运行会停止并报告失败步骤，但仍会返回屏幕图像。添加 "screenshot": false 也可以跳过最后的图像。

按图像块对齐缩小尺寸。 如果尺寸不是 28 的倍数，就要为几乎不含像素的部分图像块行或列付费。以 1920×1080 的主显示器为例，默认尺寸 1260×700 恰好对应 45×25 个图像块，共 1 125 个令牌；而 1280×720 则需 1 196 个令牌 — 像素减少 1.5%，费用却降低 6%。

抑制未变化的屏幕。 如果自上次发送图像后，变化像素占比低于 CHANGE_THRESHOLD，回复会是一行文本，而不是截图。真实桌面永远不会连续生成两帧逐字节完全相同的图像（时钟、光标、悬停状态都会变化），因此这是阈值判断，而非相等性检查。如果连续抑制达到 MAX_SKIPS 次，就会强制发送一张图像，以免模型因上下文压缩而丢失之前的图像后盲目操作。

合适尺寸的图像。 COMPUTER_USE_MAX_DIM 用于在定位准确度和成本之间取舍 — 以 1920×1080 的主显示器为例：1792 → 2 304 个令牌，1260 → 1 125 个令牌（默认值），1036 → 777 个令牌，896 → 576 个令牌。请将长边控制在 ≤ 2576 px：如果通过 tool_result 返回的图像超过模型限制，图像会被拒收，而不会缩小。

COMPUTER_USE_IMAGE_FORMAT 不能节省令牌 — Claude 按像素尺寸计费，因此相同截图的 JPEG 和 PNG 费用完全相同。JPEG 只会减小传输数据量（此处约从 977 KB 降至 141 KB），有助于降低延迟，但可能会影响小字的可读性。

安全 — 它控制着你的真实机器

这是完全自主运行的：它不会在每次操作前征求同意。三个独立的停止开关（src/safety.py）：

1. 故障保护角落 — 将鼠标猛地移到左上角 → pyautogui 会抛出 FailSafeException，操作立即中止。
2. 紧急热键 — Ctrl+Alt+Q（可配置）→ 强制终止服务进程 （os._exit(1)）。
3. STOP 覆盖层 — 始终置顶的窗口（右上角），显示当前操作，并带有一个醒目的红色 ■ STOP AGENT 按钮，也会强制终止进程。

延迟启用 / 停用： 覆盖层和全局紧急热键会在任务的首次操作时延迟启用，而不是在服务启动时启用 — 空闲会话不会显示任何内容，也不会占用热键。Agent 在任务结束时调用 action="stop" 后，它们会停用，并在下一次操作时自动重新启用。（STOP 覆盖层是一个单一的持久窗口，在休眠时会被隐藏，而不是销毁 — 重新创建窗口可能导致崩溃。）可通过 COMPUTER_USE_IDLE_STOP 启用可选的空闲自动停用功能，但默认禁用：Agent 在工具调用之间的思考时间很容易超过任何较短的空闲时长，因此，非零值会导致 Agent 在任务中途停用。

节奏控制也有助于你保持掌控：每次操作后都会暂停一段可配置的时间（COMPUTER_USE_PAUSE），光标也会平滑移动，而非瞬间跳转（COMPUTER_USE_MOVE_DURATION），方便你观察并中断操作。

请勿在无人监督的情况下，让它操作任何可能花钱、发送消息或删除数据的内容。

安装

需要 Python 3.10 或 3.11（未经 3.13+ 测试；请避免使用 3.14 测试版）。

推荐：uvx（始终使用最新版本）

无需预先安装，且每次都会自动获取所有最新发布版本 — uvx 会在每次服务启动时解析最新发布的版本，因此只需重启 MCP 客户端即可完成升级。需要安装 uv。

uvx realhands@latest

如果希望让 uv 重用已缓存的版本，请去掉 @latest（使用 uvx realhands）。

从 PyPI 安装（固定版本）

pip install realhands

这会安装 realhands 控制台脚本和可导入的 realhands 包。可通过 realhands 或 python -m realhands.server 启动服务。

如果你希望使用一个固定版本，不会在你不知情时发生变化，或者机器启动时可能处于离线状态，请选择这种方式而非 uvx — uvx realhands@latest 每次启动时都需要连接 PyPI。代价是升级需要手动进行：

pip install --upgrade realhands

然后重启 MCP 客户端 — 客户端会在会话启动时绑定服务，因此运行中的会话会继续使用旧代码，直到重启。

从源代码安装（并注册到 Claude Desktop）

git clone https://github.com/kanishka089/computer-use-mcp
cd computer-use-mcp
py -3.10 install.py

这会创建 .venv/，安装该包及其依赖（可编辑模式），如果 .env 不存在，则将 .env.example 复制为 .env，并在 Claude Desktop 的配置中注册服务（同时备份任何已有配置）。重启 Claude Desktop，然后查找 computer-use 工具。

Claude Code

将其注册为名为 realhands 的用户范围 stdio 服务。此形式会自动升级 — 每个新会话都会解析最新发布版本，因此你无需操心版本更新：

claude mcp add realhands --scope user -- uvx realhands@latest

之后，该工具会以 mcp__realhands__computer 的名称出现在每个项目中。

如果你通过 pip 安装，并希望使用固定版本，请将其指向安装了该包的 Python（并自行运行 pip install --upgrade realhands 来升级）：

claude mcp add realhands --scope user -- python -m realhands.server

已注册旧版本？ 将其重新指向自动升级形式：

claude mcp remove realhands --scope user
claude mcp add realhands --scope user -- uvx realhands@latest

在会话中移除并重新添加 MCP 会断开当前会话与它的连接 — 新注册项会在下次启动 Claude Code 时生效。

升级

使用的是 0.1.x？ 请升级。mcp 2.0 移除了 API 0.1.x 的导入，因此，虽然之前安装时解析到 mcp 1.x 的版本仍能运行，但重新安装或更换机器后，服务将无法启动。0.2.1 及更高版本兼容这两个版本。请参阅 v0.2.1。

最佳方式：切换到自动升级形式（只需一次）

之后再也不用手动升级——每次客户端重启都会获取最新版本：

claude mcp remove realhands --scope user
claude mcp add realhands --scope user -- uvx realhands@latest

重启 Claude Code。（在会话中移除并重新添加 MCP 会断开当前会话与它的连接；新的注册会在下次启动时生效。）

继续使用 pip

升级服务实际运行所用的同一个解释器——不要用 pip 恰好解析到的解释器。如果你安装在虚拟环境中，或有多个 Python，直接运行 pip install --upgrade realhands 可能会升级另一个环境，而让服务继续使用旧版本。这是升级“未生效”最常见的原因。

首先，找到解释器：

claude mcp get realhands

查看 Command: 行——这就是你的 Python。然后显式使用它升级：

& "C:\path\from\that\Command line\python.exe" -m pip install --upgrade realhands

如果 Command: 显示的是裸 python，运行 pip install --upgrade realhands 即可。

确认升级生效后，重启 Claude Code：

& "C:\path\to\python.exe" -c "import realhands; print(realhands.__version__)"

从源代码安装？

只需运行 git pull——install.py 会以可编辑模式安装软件包，因此当前代码检出目录就是已安装的版本。重启客户端。

使用

直接提出请求即可。例如：

截取屏幕截图，打开 Chrome，前往 YouTube 并搜索“lofi”。

观察真实光标移动，并查看已登录的 Chrome 如何响应。真实案例：它已在用户自己的 Chrome 登录会话中自主完成了完整的 Google Play Console 发布流程。

配置（.env，可选——默认值即可）

变量	默认值	含义
COMPUTER_USE_MAX_DIM	1260	发送给 Claude 的屏幕截图最长边；这是准确度与成本之间的主要调节项（参见Token 用量）
COMPUTER_USE_PATCH_ALIGN	1	将每个轴向下取整到 28px 的整数倍，以避免在不完整的块上消耗 Token（每张截图约可节省 6%）
COMPUTER_USE_CHANGE_THRESHOLD	0.002	移动像素比例低于此值时跳过屏幕截图（0 = 始终发送）
COMPUTER_USE_MAX_SKIPS	6	连续跳过达到此次数后，强制截取真实屏幕截图
COMPUTER_USE_MONITOR	1	默认显示器（1 = 主显示器，2.. = 其他显示器，0 = 所有屏幕）；可在每次调用时覆盖
COMPUTER_USE_IMAGE_FORMAT	png	png（文字清晰）或 jpeg（载荷较小）。不影响 Token 用量——成本按像素尺寸计算，而非字节数
COMPUTER_USE_PAUSE	0.15	每次 pyautogui 操作后的延迟时间（便于中断）
COMPUTER_USE_PANIC_HOTKEY	ctrl+alt+q	全局紧急停止快捷键
COMPUTER_USE_OVERLAY	1	显示 STOP 覆盖窗口
COMPUTER_USE_MOVE_DURATION	0.4	光标滑动时间（模拟人类移动）
COMPUTER_USE_IDLE_STOP	0	空闲达到此秒数后自动停止（0 = 从不；仅在 action="stop" 时停止）

已知问题

• Agent 在轮次之间空闲时，MCP 连接会断开。 Claude 在轮次之间思考或等待时，与 realhands 的 stdio 连接可能会悄无声息地断开。解决方法：执行一次 screenshot 操作，它会静默地重新连接。请注意，在真实机器上，报错为 Connection closed 的操作通常仍已执行——重试前先截屏并检查实际屏幕状态，否则可能会重复点击或提交。
• 点击坐标必须与截图对应的显示器一致。 如果截图时指定了 monitor=2，点击时却没有传入 monitor=2，点击就会落在主显示器上。
• activate_window 比任务栏更可靠。 Windows 的前台锁定机制会导致任务栏点击不可靠（图标只会闪烁）。activate_window 使用 AttachThreadInput、z 顺序切换以及最小化/恢复备用方案，因此切换应用时优先使用它。
• 不要使用 Python 3.13/3.14 运行。 仅在 3.10/3.11 上测试过；安装程序也会发出警告。
• 输入较长或包含 Unicode 的文本时会使用剪贴板。 剪贴板会先保存再恢复，但任何监视剪贴板的程序都会短暂看到粘贴的文本。

自测

python -m realhands.screen

截取屏幕，打印实际尺寸、发送的尺寸及缩放系数，写入 test_capture.png，并运行坐标往返检查（中心点和两个角点）。