computer-use-mcp
Enables LLM agents to control the macOS desktop, including screenshots, mouse movement and clicks, drag-and-drop, scrolling, text input, keyboard shortcuts, window inspection, clipboard access, launching apps, and interacting with macOS permissions and applications.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
computer-use-mcp
一个本地运行的 Model Context Protocol 服务,让 LLM Agent 真正操作 macOS 桌面:截屏、移动/点击鼠标、拖拽、滚动、输入文字、按快捷键、查看窗口、读写剪贴板、启动 App。
stdio MCP 服务:服务自身不监听端口;后台 Chrome 使用本机 localhost DevTools 端口,Chrome 页面可访问网络。
极简依赖:Python 标准库 + PyObjC(Quartz / AppKit),CDP WebSocket 客户端无需额外依赖。
35 个工具:包含 macOS 桌面与后台 Chrome 控制,观察类和操作类分离,支持只读模式。
坐标可换算:截图元数据直接给出「图片像素 → 屏幕坐标」的换算系数。
环境要求
macOS 12 或更高版本(在 macOS 14.5 / Apple M2 上验证)。
Python 3.10+,且能
import Quartz, AppKit。python.org 安装的系统 Python 通常已自带 PyObjC;如果没有:
python3 -m pip install pyobjc-framework-Cocoa pyobjc-framework-Quartz先确认:
python3 -c "import Quartz, AppKit; print('PyObjC ok')"Related MCP server: mcp-desktop
快速开始
cd "<path-to-computer-use-mcp>"
./bin/computer-use-mcp --version # computer-use-mcp 0.1.0
./bin/computer-use-mcp --print-tools # 查看完整工具 JSON Schema
# 端到端冒烟测试(观察类,不动鼠标)
python3 scripts/smoke_test.pybin/computer-use-mcp 会自动寻找一个带 PyObjC 的 python3,因此不需要 pip install 就能运行。需要指定解释器时:
COMPUTER_USE_MCP_PYTHON=/path/to/python3 ./bin/computer-use-mcp也可以安装为命令(可选):
python3 -m pip install -e .
computer-use-mcp接入 MCP 客户端
将示例中的 <path-to-computer-use-mcp> 替换为本地项目目录的绝对路径。
StepCode(~/.stepcode/config.toml)
[mcp_servers.computer-use]
command = "<path-to-computer-use-mcp>/bin/computer-use-mcp"
args = []
enabled = true只读模式:
[mcp_servers.computer-use.env]
COMPUTER_USE_MCP_READ_ONLY = "1"Claude Desktop / 其他 JSON 配置
见 examples/claude-desktop-config.json:
{
"mcpServers": {
"computer-use": {
"command": "<path-to-computer-use-mcp>/bin/computer-use-mcp",
"args": []
}
}
}通用形式永远是:
command: /绝对路径/computer-use-mcp/bin/computer-use-mcp
args: []
transport: stdio权限(必须)
macOS 会按启动这个 MCP 服务的宿主程序授予权限,而不是按脚本路径。通常需要给 StepCode / Terminal / iTerm 授权,然后重启宿主程序和 MCP 服务。
辅助功能(Accessibility) — 合成鼠标 / 键盘事件。
系统设置 → 隐私与安全性 → 辅助功能屏幕录制(Screen Recording) — 截屏。
系统设置 → 隐私与安全性 → 屏幕录制
授权后可在 Agent 中调用:
{"name": "get_permissions", "arguments": {}}返回:
{
"accessibility": true,
"screen_recording": true,
"screen_locked": false,
"frontmost_app": {"name": "Safari", "bundle_id": "com.apple.Safari", "pid": 1234}
}如果为 false,可以调用 open_permission_settings 直接打开对应面板。
锁屏注意:
screen_locked: true时,截图看到的是锁屏界面,合成输入无法送达应用窗口。请先解锁 Mac;get_screen_info和截图元数据会返回warning字段提醒调用方。为避免把按键送进登录密码框,锁屏状态下type_text/press_keys/key_down/key_up的全局注入会被拒绝;显式指定target_pid的直投仍可用。
坐标系统与截图
所有坐标单位是 screen points(逻辑点,不是 Retina 像素)。
原点在主显示器左上角,X 向右,Y 向下。
多显示器时,主屏左侧 / 上方的屏幕坐标为负数。
get_screen_info会返回每块屏幕的bounds。截图默认:
resolution: "logical"→ 未触发max_dimension缩小时,1 个图片像素 = 1 个屏幕点;max_dimension: 1600→ 最长边超过 1600 时等比缩小;format: "png"。
截图返回的文本元数据包含:
{
"image_width": 1600,
"image_height": 1000,
"region": {"x": 0, "y": 0, "width": 1440, "height": 900},
"coordinate_mapping": {
"points_per_image_pixel_x": 0.9,
"points_per_image_pixel_y": 0.9
}
}把模型在图片上估的像素坐标换算成工具坐标:
screen_x = region.x + image_x * points_per_image_pixel_x
screen_y = region.y + image_y * points_per_image_pixel_y需要原始 Retina 分辨率时传 resolution: "native", max_dimension: 0;只需要局部细节时传 x / y / width / height 区域截图,避免整屏缩小后看不清小字。
工具
观察
工具 | 说明 |
| 显示器、缩放、光标、虚拟桌面、权限、锁屏状态、前台 App。建议先调用。 |
| 全屏 / 区域 / 窗口截图。参数: |
| 按前后顺序列出窗口: |
| 当前光标坐标。 |
| 辅助功能 / 屏幕录制 / 锁屏 / 前台 App。 |
| 读取剪贴板文本。 |
| 等待 |
鼠标
工具 | 说明 |
|
|
|
|
| 按住 / 松开鼠标键,用于手动拖拽。 |
|
|
|
|
键盘
工具 | 说明 |
|
|
|
|
| 单独按住 / 释放按键或修饰键。 |
支持 cmd/command、shift、option/alt、control/ctrl、fn,以及 enter、esc、tab、space、backspace、方向键、f1–f20、pageup/pgdn/home/end 等。
窗口、App、系统
工具 | 说明 |
| 激活窗口所属 App 并前置。若同 App 有多个窗口,之后再点击目标窗口。 |
| 将已运行的 App 置前;未运行则启动。 |
| 按名称、路径或 bundle id 启动 App。 |
| 仅允许 |
| 打开辅助功能 / 屏幕录制设置面板。 |
后台 Chrome(Chrome DevTools Protocol)
这组工具通过 Chrome DevTools Protocol 控制标签页,不激活窗口、不用 Spotlight、不移动桌面鼠标。chrome_start 会启动独立的无头 Chrome,使用单独的持久化用户目录 ~/Library/Application Support/computer-use-mcp/chrome;可在 MCP 服务重启后继续连接。它不会复用日常 Chrome 配置或其登录状态。
工具 | 说明 |
| 启动后台 Chrome,可传 |
| 检查后台实例状态。 |
| 连接已启用远程调试的本机 Chrome,参数为 |
| 列出、打开、导航、关闭标签页。 |
| 读取页面标题、URL、可见文本或后台截图。 |
| 通过 CDP 鼠标事件点击可见元素,或聚焦输入框并写入文本。 |
| 关闭本工具启动的独立 Chrome;拒绝关闭外部连接的实例。 |
最短调用流程:
chrome_start({"url":"https://example.com"})
chrome_tabs({})
chrome_read_page({"tab_id":"上一步返回的 tab_id"})
chrome_screenshot({"tab_id":"上一步返回的 tab_id"})从 MCP 客户端调用 chrome_start 后,无需保持 Chrome 窗口在前台。若要接管一个额外启动并启用了调试的 Chrome,可在启动 Chrome 时传入 --remote-debugging-port=9222 --user-data-dir=/独立的/用户目录,再调用 chrome_connect({"port":9222})。为避免泄露浏览器会话,不要对日常个人资料目录开放调试端口。macOS 上 Chrome 136+ 仅对非默认用户目录开放远程调试。
仅允许 http、https 和 about:blank 页面地址;端口及 WebSocket 必须是 localhost。页面点击、表单输入、导航和关闭标签会实际改变网页状态。此实现不暴露任意 JavaScript 执行工具。
只读模式
两种开启方式:
./bin/computer-use-mcp --read-only
COMPUTER_USE_MCP_READ_ONLY=1 ./bin/computer-use-mcp只读模式下,桌面输入操作、启动 / 停止 Chrome、打开 / 导航 / 关闭标签、页面点击和输入会返回 isError: true;桌面截图、Chrome 状态 / 标签 / 页面读取仍然可用。
典型 Agent 工作流
1. get_screen_info
→ 确认屏幕、权限、是否锁屏、前台 App
2. screenshot {"max_dimension": 1600}
→ 看截图,定位目标
3. click {"x": 742, "y": 318}
或 type_text {"text": "hello"}
或 press_keys {"keys": "cmd+s"}
4. screenshot {"x": 600, "y": 200, "width": 600, "height": 400}
→ 用局部截图确认结果给模型的提示词示例:
打开 Safari,搜索「Model Context Protocol」,把第一条结果的标题和链接告诉我。每步操作后截图确认。
安全设计
MCP 服务仅使用 stdio;本机 Chrome 另通过 loopback-only DevTools 端口通信,Chrome 页面本身可能访问外网。
不提供 shell / 任意 JavaScript 执行工具。
浏览器 URL 限制为
http/https/about:blank并拒绝凭据;DevTools HTTP 不跟随重定向,WebSocket 地址与连接均限定在 localhost。stderr 日志会脱敏:不记录输入的文本、URL、按键、App 名、
target_pid的具体值,只记录长度 / 类型。合成输入可以造成真实后果(删除、发送、购买)。默认建议在 Agent 侧对危险动作做人工确认;不确定时使用只读模式。
clipboard_read可能读到密码等敏感内容,仅在需要时使用。
项目结构
computer-use-mcp/
├── bin/computer-use-mcp # 免安装启动器(自动找带 PyObjC 的 python3)
├── src/computer_use_mcp/
│ ├── server.py # MCP stdio JSON-RPC
│ ├── tools.py # 35 个工具的 JSON Schema 与分发
│ ├── chrome.py # 隔离后台 Chrome + DevTools Protocol
│ ├── macos.py # Quartz/AppKit 桌面控制
│ └── keymap.py # macOS 虚拟键码与快捷键解析
├── tests/ # 标准库 unittest(无需 pytest)
├── scripts/smoke_test.py # 通过 stdio 启动真实服务做端到端测试
├── examples/ # 客户端 Demo + StepCode/Claude 配置
├── pyproject.toml
└── README.md测试
# 单元测试(协议、键位、坐标、参数校验)
PYTHONPATH=src python3 -m unittest discover -s tests -v
# 端到端:握手、工具列表、权限、截屏、窗口截图、错误码、只读模式
python3 scripts/smoke_test.py
# 额外验证真实输入(会移动鼠标;可选向测试 App 注入文字)
python3 scripts/smoke_test.py --input
python3 scripts/smoke_test.py --input --target-pid 12345一次实际运行结果:
58 tests OK
PASS: computer-use-mcp is working
display: 1440.0x900.0 points, scale 2.0
permissions: accessibility=True screen_recording=True screen_locked=False额外验证:
用官方 Python MCP SDK
1.30.0的ClientSession通过 stdio 完成initialize/tools/list/tools/call,并正确解析了返回的ImageContent。对一个本地测试 Cocoa App:验证了单击、双击(本地事件监视器收到 1 次/2 次 mouseDown)、Unicode 文本注入(含中文),以及
shift+left这类带修饰键的按键(ABC→ 选中C→ 输入Z得到ABZ)。锁屏时
get_screen_info/ 截图会返回warning,全局键盘输入会被拒绝,避免把按键送进登录密码框。
已知限制
仅 macOS;依赖 Quartz / AppKit。
锁屏时输入不会到达普通应用窗口;请先解锁。
密码框等 secure input 会刻意忽略合成键盘事件。
focus_window只能激活 App;同一 App 的多个窗口需要通过点击来精确前置(未使用 AXRaise)。受保护窗口(如部分系统窗口、DRM 内容)可能无法截图。
某些游戏 / 远程桌面 / 虚拟机使用底层输入抓取,可能忽略合成事件。
不包含 OCR;识别截图内容由调用方模型完成。
多用户 / 远程桌面场景未专门验证。
故障排查
现象 | 处理 |
| 安装 PyObjC,或用 |
工具列表为空 | 客户端配置里 |
权限显示 | 权限授予的是启动服务的宿主程序;改完后重启宿主程序和 MCP 服务。 |
截图全黑 / 失败 | 检查屏幕录制权限;锁屏时只能看到锁屏画面。 |
中文输入失败 | 用 |
快捷键没反应 | 确认目标 App 在前台;必要时先 |
想看服务日志 | 客户端通常把 stderr 显示在 MCP 日志中;也可手动运行 |
License
MIT,见 LICENSE。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Let AI agents use your real, signed-in Chrome: tabs, clicks, forms, screenshots and video.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to automate macOS desktop tasks including mouse control, keyboard input, screenshots, window management, and UI interaction.417MIT
- FlicenseNot gradedqualityDmaintenancemacOS desktop automation enabling AI agents to screenshot, switch apps and tabs, click, type, and scroll. Offers two trust levels: read-only screenshot and full UI control.-
- AlicenseNot gradedqualityDmaintenanceProvides native macOS desktop automation for AI agents, enabling screen capture, mouse/keyboard control, window management, and iOS/Android simulator control in both foreground and background modes without focus stealing.6MIT
- AlicenseAqualityDmaintenanceEnables AI agents to control macOS desktop apps via screenshots, mouse clicks, keyboard input, accessibility queries, and AppleScript.118 npmMIT