Skip to main content
Glama
FloraAurella

computer-mcp

by FloraAurella
OverviewSchemaRelated ServersScoreDiscussions
Rust
Local

computer-runtime

跨平台 GUI 自动化运行时 + MCP Server。用同一套统一 API 在 macOS / Windows / Linux(X11) 上完成桌面 GUI 元素的读取、点击、输入、快捷键和截图，并通过 Playwright + DOM/ARIA 提供浏览器高速结构化控制；桌面操作提供稳定 windowId、事件式 waitFor 与结果 verify。全部能力通过 MCP（Model Context Protocol） 对外暴露，可供任意 MCP 宿主（如 AI 助手）直接驱动。

                 MCP Client / AI Host
                          │
                  ┌──────────────┐
                  │  MCP Server  │ 25 tools: computer.* + browser.*
                  └──────┬───────┘
          ┌──────────────┴──────────────┐
          ▼                             ▼
   computer.* (stdio JSON-RPC)     browser.* (in-process)
          ▼                             ▼
 Computer Runtime (Rust)         Browser Runtime (TS)
          │                        Playwright + DOM/ARIA + CDP
 ┌────────┼────────┐                     │
Win     macOS     Linux                ▼
UIA      AX      AT-SPI/XTest     Chromium/Chrome/Edge

核心设计原则：语义动作优先于物理动作（优先走系统无障碍 API 的语义操作，物理点击/键入只作兜底）、上层永不接触平台原生句柄、主同步路径禁止固定 sleep、测试不依赖 LLM 与公网。

一、环境要求

依赖

版本要求

用途

Rust (cargo)

stable

编译桌面 Runtime

Node.js

18+（20+ 推荐）

MCP Server / Browser Runtime / 测试

npm

9+

TS 工作区构建

Chrome / Edge（可选）

本机已安装即可

browser.* 自动探测，无需另装 Playwright 浏览器

Xcode Command Line Tools（仅 macOS）

与当前 macOS SDK 匹配

编译 ScreenCaptureKit 的 Objective-C/ARC 桥接层（xcrun clang）

系统权限（macOS 必须，首次运行时授权一次即可）

在 系统设置 → 隐私与安全性 中，给你的终端 / MCP 宿主 App 开启：

  • 辅助功能（Accessibility） —— 读取窗口元素树、语义点击、窗口聚焦

  • 屏幕与系统音频录制（Screen & System Audio Recording） —— ScreenCaptureKit 全屏/指定窗口截图

截图状态可通过 computer_capabilities 或 Runtime CLI 的 capabilities 查看。macOS 会分别报告：

  • screen_capture.permission：TCC 预检是否通过；

  • screen_capture.available：真实小尺寸截图探测是否成功；

  • screen_capture.backend：实际服务截图的 screencapturekit、screencapture-cli 或 none。

权限、后端缺失和后端执行失败分别返回 SCREEN_CAPTURE_PERMISSION_DENIED、 SCREEN_CAPTURE_BACKEND_UNAVAILABLE 和 SCREEN_CAPTURE_BACKEND_FAILED，不会再把所有失败都猜成权限问题。

Linux 仅支持 X11 会话（Wayland 显式返回 UNSUPPORTED）；Windows 需要 Windows 10 1809+。

Related MCP server: Touchpoint

二、安装（构建）

git clone <repo-url> computer-use-mcp
cd computer-use-mcp

# 1. 桌面 Runtime（Rust）→ 产物 target/release/computer-runtime
cargo build --release -p computer-runtime-ipc

# 2. MCP Server + SDK + Browser Runtime（TypeScript 工作区）
npm install
npm run build

macOS 构建时，runtime/platform/macos/build.rs 会通过 xcrun clang 编译一个很小的 Objective-C/ARC 桥接层。它负责 ScreenCaptureKit completion block 的创建与生命周期， 因此需要已安装 Xcode Command Line Tools；不需要额外下载第三方原生依赖。

构建完成后的关键产物：

target/release/computer-runtime                    # 桌面 Runtime 二进制（含 CLI 与 stdio 服务）
packages/mcp-server/dist/index.js                  # MCP Server 入口（bin 名 computer-mcp）

仅运行测试时才需要：cd apps/test-gui && npm install && npm run build（Electron 测试 GUI）。

三、运行

本项目没有常驻守护进程：MCP 宿主负责拉起 MCP Server，Server 再按会话启动桌面 Runtime。你只需要配置一次 MCP，之后即插即用。

方式 1：接入 MCP 宿主（推荐）

在你的 MCP 宿主配置文件（如 mcp.json / claude_desktop_config.json 等）中加入：

{
  "mcpServers": {
    "computer": {
      "command": "node",
      "args": ["/absolute/path/to/computer-use-mcp/packages/mcp-server/dist/index.js"],
      "env": {
        "COMPUTER_RUNTIME_BIN": "/absolute/path/to/computer-use-mcp/target/release/computer-runtime"
      }
    }
  }
}

注意：args 与 COMPUTER_RUNTIME_BIN 必须写成绝对路径（换成你自己的克隆目录）。

macOS 建议把 release 二进制复制/安装到一个稳定路径，并让 COMPUTER_RUNTIME_BIN 指向该路径。Cargo 会反复替换 target/release 下的构建产物， macOS TCC 可能继续关联旧的执行身份，表现为“预检允许，但 ScreenCaptureKit completion 超时”。稳定安装路径只需在系统设置中授权一次。

默认 COMPUTER_TOOL_PROFILE=full 时会得到 25 个工具：

分类

工具

computer.*（桌面，14 个）

computer_capabilities computer_windows computer_observe computer_click computer_type computer_key computer_screenshot computer_wait computer_verify computer_visual_observe computer_resolve computer_screenshot_image computer_capture_region computer_register_visual_target

browser.*（浏览器，11 个）

browser_launch browser_pages browser_observe browser_navigate browser_click browser_type browser_key browser_screenshot browser_evaluate browser_wait browser_verify

computer_click 还支持 visual_N 目标（来自 computer_visual_observe 或 computer_register_visual_target）以及 query + expect 混合解析与点击后验证 （协议 0.4.0，见 docs/protocol-v3.md 与 docs/migration-0.3-to-0.4.md）。

截图不再返回大块 base64（协议 0.4.0）：computer_screenshot / browser_screenshot 默认返回 <2KB 的 capture_N 元数据引用（CaptureReference）， 像素只留在服务端（TTL 10min / LRU 64 条 / 128MB）。需要真正看图时走三条显式通道： MCP resource computer://capture/{id}（Host 原生图片桥）、 computer_screenshot_image（危险的 raw escape hatch，默认禁用）、 computer_capture_region（高清 ROI 裁剪）。这防止了部分宿主把 {type:"image"} 结果 stringify 成文本、单张截图吃掉上百万 token 的事故。

可选环境变量（加在上面配置的 env 里）：

变量

作用

COMPUTER_RUNTIME_ARGS=--mock

使用内置 Mock 平台——无需真实 GUI 与系统权限，用于验证整条链路

COMPUTER_BROWSER_HEADED=1

browser.* 用有头浏览器（默认无头）

COMPUTER_ENABLE_EVALUATE=0

关闭 browser_evaluate（安全收紧）

COMPUTER_VISION_ENABLED=1

开启视觉 grounding（默认关闭；computer_visual_observe/computer_resolve 视觉回退需要）

COMPUTER_VISION_PROVIDER=mock|remote|openai-compatible

视觉 provider（默认 mock，纯本地）；openai-compatible 调用多模态 /chat/completions

COMPUTER_VISION_REMOTE_UPLOAD=1

所有远程 provider 的第二道开关：不设置则绝不会向外部端点上传截图

COMPUTER_VISION_BASE_URL / COMPUTER_VISION_MODEL / COMPUTER_VISION_API_KEY

openai-compatible 的 API 根地址、模型和可选密钥

COMPUTER_VISION_MAX_RETRIES / COMPUTER_VISION_MAX_IMAGE_BYTES

Managed Vision 的重试上限（默认 1）和图像上限（默认 8MiB）

COMPUTER_TOOL_PROFILE=desktop-core|desktop-vision|browser|full|debug

静态工具面；默认 full 兼容旧 Host，日常建议按场景缩到 9–13 个工具

COMPUTER_CONTEXT_METRICS=1

把 schema 字符数、Tool Result 字节数、元素数和视觉尝试写到 stderr；不会回传给模型

COMPUTER_SCREENSHOT_MODE=reference|image|auto

截图返回语义，默认 reference（如上）；image 恢复 0.3 的原始图片行为

COMPUTER_LEGACY_SCREENSHOT=1

短期过渡：同 image，带弃用警告

COMPUTER_ALLOW_RAW_IMAGE_CONTENT=1

显式允许 computer_screenshot_image 返回 ImageContent；仅用于确认不会把图片 stringify 进历史记录的 Host，默认禁用

COMPUTER_CAPTURE_TTL_MS

capture 字节 TTL（默认 600000，即 10 分钟）

COMPUTER_CAPTURE_MAX_EDGE

预览图最长边（默认 1568，视觉模型友好）

模型调度规则见仓库内的 computer-mcp-execution Skill：结构化优先、 Vision 仅作 fallback、computer_click 三种定位方式严格互斥。完整对话历史、历史 reasoning、 旧图片保留和逐轮动态工具集属于 Host/Agent Runtime；MCP Server 只负责压缩单次 Tool Result 与静态工具面，不能从宿主上下文中删除历史消息。

方式 2：CLI 直接调试（不经过 MCP）

桌面 Runtime 自带 CLI，适合手动验证权限与能力：

target/release/computer-runtime capabilities        # 查看当前平台能力与权限状态
target/release/computer-runtime windows             # 枚举窗口（稳定 windowId）
target/release/computer-runtime observe             # 观察活动窗口元素树
target/release/computer-runtime screenshot out.png  # 全屏截图
target/release/computer-runtime click 655,544       # 物理点击（自动激活窗口）
target/release/computer-runtime key cmd+a           # 快捷键（cmd+a / enter / esc 等）
target/release/computer-runtime --mock observe      # Mock 平台，无需 GUI/权限

macOS 截图后端与排障

macOS 14+ 默认使用 ScreenCaptureKit。SCK 的完整异步管线由 Clang/ARC 原生桥接层执行：

getShareableContent → 选择 SCDisplay / SCWindow
                    → 构建 SCContentFilter / SCStreamConfiguration
                    → SCScreenshotManager → retained CGImageRef → Rust RGBA

桥接层不会在 getShareableContent completion handler 内等待嵌套截图 completion， 避免占住 ScreenCaptureKit 的内部串行队列。每次原生请求有 10 秒上限；失败时自动尝试系统 /usr/sbin/screencapture，并在日志和 capability 的 backend 中诚实显示 fallback。

正常输出应类似：

{
  "screen_capture": {
    "permission": true,
    "available": true,
    "backend": "screencapturekit"
  }
}

如果 permission 为 true，但 backend 变成 screencapture-cli，请先确认启动 Runtime 的终端或 MCP 宿主已经获得“屏幕与系统音频录制”权限。若问题只发生在反复覆盖的 target/release/computer-runtime，把二进制复制到稳定安装路径后重新授权该宿主：

cargo build --release -p computer-runtime-ipc
cp target/release/computer-runtime /absolute/stable/path/computer-runtime
/absolute/stable/path/computer-runtime capabilities
/absolute/stable/path/computer-runtime screenshot /tmp/computer-runtime-check.png

不要通过长期降低 Rust release 优化级别规避该问题；当前实现使用默认 opt3，并已在同一 release 执行实体上完成全屏截图 200/200、指定窗口截图 200/200 的零 fallback 验收。

方式 3：SDK 编程调用（TypeScript）

import { RuntimeClient } from "computer-runtime-client-sdk";

const client = new RuntimeClient({
  binaryPath: "/absolute/path/to/computer-use-mcp/target/release/computer-runtime",
});
const wins = await client.listWindows();
const obs = await client.observe({ window: wins[0].id });   // 定向观察，不抢焦点
await client.click({ elementId: "ui_5" });                  // 语义点击
await client.stop();                                        // 回收子进程

四、快速自检

配置完成后，按顺序跑一遍即可确认链路健康：

# 1. 权限与能力（macOS 上应看到 screen_capture.backend = "screencapturekit"）
target/release/computer-runtime capabilities

# 2. 无 GUI 依赖的 Mock 链路
target/release/computer-runtime --mock observe

# 3.（可选）跑自动化测试验证完整安装
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
node tests/integration/run.mjs --mock   # Mock 桌面集成
node tests/integration/run.mjs          # 真机桌面集成（自动拉起测试 GUI）
node tests/browser/run.mjs              # 浏览器 Fast Path 集成（本地测试站点）

五、平台支持状态

能力

macOS

Windows

Linux X11

Browser

窗口枚举 + 稳定 windowId

✅ 已验证

✅*

✅*

page_N ✅

observe(windowId) 定向观察

✅ 已验证

✅*

✅*

✅

窗口激活（autoActivate）

✅ 已验证

✅*

✅*

n/a

语义动作（AX / UIA / AT-SPI / locator）

✅ 已验证

✅*

✅*

✅

物理输入（CGEvent / SendInput / XTest）

✅ 已验证

✅*

✅*（ASCII）

✅

截图（全屏 / 指定窗口）

✅ 已验证

✅*

仅全屏

✅

waitFor / verify

✅ 已验证

✅

✅

✅ 事件驱动

* 代码完成并在对应平台目标上通过编译 + 单测（CI 三平台覆盖），真机 GUI 集成验收待对应平台环境。当前版本推荐在 macOS 上使用。

测试与基准（面向贡献者）

cargo test --workspace                  # Rust 单元测试 + Mock 全流程
npm run test:unit                       # TS 单元测试
node tests/integration/mcp_verify.mjs   # MCP 20 工具面端到端
node tests/soak.mjs                     # 稳定性压测（mock 1000 轮 / --real 300 轮）
node benchmarks/bench.mjs               # 性能基准（截图/observe p50/p95/max）
node benchmarks/bench.mjs --browser     # 浏览器链路基准

六、目录结构

runtime/core             平台无关核心（Window Registry、Element Registry、wait/verify、事件抽象、Mock）
runtime/platform/macos   AX + CGEvent + CGWindowList + ScreenCaptureKit（Clang/ARC bridge）
runtime/platform/windows UIA COM + Win32 + SendInput + GDI
runtime/platform/linux   AT-SPI (D-Bus) + x11rb + XTest + XGetImage
runtime/ipc              computer-runtime 二进制（stdio JSON-RPC + CLI）
packages/protocol        冻结协议类型（v0.2.0）
packages/client-sdk      类型化客户端（参数校验 + 生命周期管理）
packages/browser-runtime 浏览器运行时（playwright-core，自动探测本机浏览器）
packages/mcp-server      MCP Server（20 tools）
apps/test-gui            Electron 测试 GUI（双窗口 / 延迟状态 / disabled 控件）
apps/test-web            本地测试站点（login/search/modal/tabs/dynamic/navigation）
tests/                   桌面集成 + 浏览器集成 + MCP E2E + soak
benchmarks/              性能基准脚本与结果

This server cannot be installed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd
A
license - permissive license
Not graded
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • Skyvern

    AI-powered browser automation — navigate, click, fill forms, and extract data from any website.

  • browserbasehq-mcp-browserbase

    Provides cloud browser automation capabilities using Stagehand and Browserbase, enabling LLMs to i…

  • SentinelX MCP

    Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/FloraAurella/computer-use-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server