computer-copilot

让 AI 像人一样操作 Windows 桌面的 MCP 服务器

看得见的操控 · 管得住的权限 · 默认不截图

许可证: MIT · 仅支持 Windows 10/11 · Python 3.10+

这是什么

一个给 LLM 用的 MCP（Model Context Protocol）服务器，把 Windows 桌面变成 AI 可以操作的对象： 找窗口、点按钮、敲键盘、读界面文字、启动软件、截屏 —— 全部通过标准 MCP 工具暴露给 Claude / DeepSeek / Cursor / ZCode / DSH 等任意 MCP 客户端。

它不是一个「截图 → 识图 → 猜坐标」的玩具。默认路径不截图：

设计原则：AI 平时不截图。 截图很贵 —— 传输慢、token 多、还会泄露屏幕上无关的内容。所以默认走控件接口 / OCR； 只有当「用户要看」「需要作证」时才截图。截图范围可限定为只截当前目标窗口。

Related MCP server: OpenSky

亮点

• 看得见的操控：操控时在目标窗口画高亮边框 + AI 光标 + 操作流水，顶部有横幅提示。

• 管得住：可随时通过 panel 工具暂停 / 切「仅观察」/ 一键叫停；用户一旦自己动鼠标键盘，AI 立刻让路。

• 隐私可控：截图范围可限定为只截当前操控的目标窗口，不碰屏幕其它内容。

• 不弹黑窗：启动 GUI 程序用 detached 方式，自动隐藏附带控制台窗口（ModelSim 这类程序也管得住）。

• Windows 原生 OCR：走 WinRT OCR 引擎，中英文都准，不依赖任何外部模型或 API。

• 遮挡也能读：PrintWindow 截图可以在窗口被别的窗口压住时拿到完整内容。

• 编号点击：截图里把可点元素标号，模型说"点 3 号"即可，落点由 UIA/OCR 真值决定，不靠模型心算坐标。

• 单一 MCP 服务：其余全是标准工具，客户端可以随意替换。

演示

AI 通过 MCP 操控计算器完成 25 × 4 = 100：青色光环是 AI 光标，扩散波纹是点击反馈，全程通过 UIA 语义调用完成。

安装

git clone https://github.com/Jasmineee007/computer-copilot.git
cd computer-copilot
pip install -e .

依赖：mcp pillow pyautogui pyperclip uiautomation python-docx（pip install -e . 会自动装）。 OCR 用 Windows 自带 WinRT，免安装；需系统有「中文(简体)」或英文 OCR 语言包（Win10 20H1+ 默认已带）。

接入 MCP 客户端

方式一：直接指向命令（装好后 computer-copilot 在 PATH 上）

{
  "mcpServers": {
    "computer-copilot": {
      "command": "computer-copilot",
      "args": [],
      "env": { "SCREENSHOT_DIR": "C:/Users/you/screenshots" }
    }
  }
}

方式二：用自带的启动器（免改环境变量，脚本自定位包目录）——把 mcp_launch.cmd 的绝对路径给客户端：

{
  "mcpServers": {
    "computer-copilot": {
      "command": "C:/path/to/computer_copilot/mcp_launch.cmd",
      "args": []
    }
  }
}

SCREENSHOT_DIR 决定截图落到哪个目录（建议给一个专门目录，方便清理）。 COPILOT_IDLE_SECS 调「用户动键鼠后 AI 让路」的阈值秒数（0 关闭仲裁）。

工具一览（54 个）

窗口 / 进程

操控

视觉 / 读

实用工具

文档 / 控制

状态与安全（无独立面板，全走工具）

• panel(action='status') 查状态 / set_pause 暂停恢复 / set_mode(mode='observe') 仅观察 / set_scope 截图范围 / clear 清空记录。

• 仅观察模式：键鼠/窗口操控全部拒绝（返回 OBSERVE_ONLY），截图与读取仍可用。

• 物理急停：把鼠标快速甩到屏幕左上角即触发 pyautogui failsafe，立即中止自动化；或直接结束 MCP 进程。

• 用户优先：检测到真实键鼠输入即让出控制权（COPILOT_IDLE_SECS 可调）。

快速上手

在 MCP 客户端里配置好本服务后，直接用自然语言下指令即可：

• 「打开计算器，算一下 25 × 4」

• 「在记事本里写下这段话并保存到桌面」

• 「读出当前窗口里所有按钮的名字」

也可以直接在终端以 stdio 方式启动服务，交给任意 MCP 客户端连接：

computer-copilot

各工具的设计取舍见 docs/architecture.md。

风险提示（请认真读）

这个项目真的会操作你正在用的桌面：能点按钮、敲键盘、发快捷键。

• 请优先在虚拟机 / 测试环境里跑，不要对着存有重要数据的生产机授权。

• 涉及删除、付款、发送等不可逆操作，请让 AI 先复述计划再执行。

• 用户一旦自己动鼠标或键盘，AI 会主动让路；也可随时 panel(set_pause) 或甩鼠标到左上角急停。

• 截图默认只取目标窗口，但请自行确认目标窗口里没有敏感信息。

目录结构

src/computer_copilot/     真正的实现
  server.py               MCP 工具定义（对外接口，54 个工具）
  element.py / element_marks.py  UIA 控件操作 / 元素编号点击
  vision.py / ocr.ps1     OCR 读文字（以文找位）
  capture.py              截图（窗口 / 区域 / 整屏 / 坐标网格）
  control.py              键鼠输入
  overlay.py              AI 操控叠加层（边框 / 光标 / 横幅）
  status_hub.py           进程内状态中枢（暂停 / 仅观察 / 截图范围门控）
  input_guard.py          用户优先：人一动，AI 让路
  extras.py               条件等待 / 剪贴板 / 网页 / 文件 / 注册表 / 通知
  sysops.py / docs.py     进程与命令 / Word 文档
tests/                    单元测试（坐标换算等纯函数）
docs/                     架构、隐私模型

致谢

• MCP Python SDK

• uiautomation

• Windows-MCP —— 叠加层渲染方案（UpdateLayeredWindow + 预乘 BGRA）、屏幕四边呼吸光晕、物理输入仲裁等思路借鉴自该项目

• Windows 内置 OCR（WinRT Windows.Media.Ocr）

许可证

MIT，见 LICENSE。