AI导哈

桌面自动化工具

一款基于MCP协议的Windows桌面自动化工具，支持屏幕截图、键盘鼠标控制、本地OCR及图像处理功能。

  • by Xuan-BOMS
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 Xuan-BOMS/desktop-mcp

使用说明

桌面MCP

基于MCP的Windows桌面自动化 stdio，具有屏幕截图观察、键盘和鼠标控制、本地OCR和图像读取模型的屏幕截图切换桥。

发生了什么变化

此存储库现在与当前存储库匹配 desktop_mcp.py 实现在本地使用，并为添加了混合工作流 CC Switch 样式设置：

  • 文本规划可以使用具有自动 CC Switch 后备方案
  • 屏幕截图可以通过OCR在本地处理
  • 当OCR不够时，该工具可以将屏幕截图打包为当前聊天模型的切换，以便手动检查
  • 阅读后可以清理临时截图作业
  • 纯文本模型调用可以在可配置的本地重试 CC Switch 主网关被阻止或不可用时的端点

这避免了依赖代理端映像支持，同时保持了MCP自动化的可用性。

特性

  • 屏幕截图
  • 桌面操作：
    • 鼠标移动、单击、双击、右键单击、中键单击、拖动、滚动
    • 键盘类型、按键、热键、向下键、向上键
  • MCP工具：
    • desktop_observe
    • desktop_action
    • desktop_goal
    • desktop_cleanup
  • 本地观测模式：
    • --local-only
    • --local-ocr
    • --handoff
  • 目标模式，具有OCR首次验证和切换回退功能

仓库布局

desktop-mcp/
  desktop_mcp.py
  desktop-mcp.cmd
  requirements.txt
  mcp.config.example.json
  README.md
  README.zh-CN.md
  LICENSE

需求

  • Windows 10/11
  • Python 3.10+
  • 活动桌面会话

安装

git clone https://github.com/Xuan-BOMS/desktop-mcp.git
cd desktop-mcp
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt

跑

本地CLI调试：

python desktop_mcp.py action position --json
python desktop_mcp.py observe --local-only --json

以MCP服务器运行：

python desktop_mcp.py mcp-serve

或者：

desktop-mcp.cmd mcp-serve

MCP客户端配置

使用 mcp.config.example.json 作为模板。

基本stdio示例：

{
  "type": "stdio",
  "command": "C:/Python312/python.exe",
  "args": [
    "C:/path/to/desktop-mcp/desktop_mcp.py",
    "mcp-serve"
  ],
  "env": {
    "OI_THIRD_PARTY_API_BASE": "https://your-primary-gateway/v1",
    "OI_THIRD_PARTY_API_KEY": "sk-your-primary-key",
    "OI_THIRD_PARTY_MODEL": "gpt-5.3-codex",
    "DESKTOP_MCP_CC_SWITCH_ENABLED": "true",
    "DESKTOP_MCP_CC_SWITCH_BASE_URL": "http://127.0.0.1:15721/v1",
    "DESKTOP_MCP_CC_SWITCH_API_KEY": "sk-local-test",
    "DESKTOP_MCP_CC_SWITCH_MODEL": "gpt-5.3-codex"
  }
}

CC开关适配

desktop_mcp.py 现在使用两个文本规划渠道：

  1. 主网关：
    • OI_THIRD_PARTY_API_BASE, OI_THIRD_PARTY_API_KEY, OI_THIRD_PARTY_MODEL
    • 或通用OpenAI兼容envs，如果 OI_THIRD_PARTY_* 未设置
  2. 后备方案 CC Switch 网关：
    • DESKTOP_MCP_CC_SWITCH_BASE_URL
    • DESKTOP_MCP_CC_SWITCH_API_KEY
    • DESKTOP_MCP_CC_SWITCH_MODEL

推荐的本地回退配置 CC Switch 代理：

$env:DESKTOP_MCP_CC_SWITCH_ENABLED = "true"
$env:DESKTOP_MCP_CC_SWITCH_BASE_URL = "http://127.0.0.1:15721/v1"
$env:DESKTOP_MCP_CC_SWITCH_API_KEY = "sk-local-test"
$env:DESKTOP_MCP_CC_SWITCH_MODEL = "gpt-5.3-codex"

笔记：

  • DESKTOP_MCP_CC_SWITCH_BASE_URL 是用于更换主机或端口的可展开旋钮
  • 纯文本模型调用重试 CC Switch 当主路径因网关或可用性错误而失败时
  • 基于图像的观察调用不会自动回退到 CC Switch；改用本地OCR或切换截图
  • ANTHROPIC_* 如果您已经在本地使用它，它仍然被接受为兼容性回退源

观察模式

1.仅本地截图

只需捕获和保存元数据，无需OCR或模型调用：

python desktop_mcp.py observe --local-only --json

2.本地OCR

捕获屏幕截图并运行本地OCR rapidocr_onnxruntime:

python desktop_mcp.py observe --local-ocr --json

在响应被使用后自动删除已保存的屏幕截图：

python desktop_mcp.py observe --local-ocr --delete-after-read --json

3.交接桥

如果OCR不足，请打包当前模型的屏幕截图，以便在聊天中检查：

python desktop_mcp.py observe --handoff --goal "Open Google and search google" --question "Inspect the screenshot and decide the next desktop action." --json

输出包括：

  • job_id
  • 保存的屏幕截图路径
  • 提示文本，告诉操作员/模型接下来要检查什么

读取屏幕截图后，删除临时文件：

python desktop_mcp.py cleanup --job-id <JOB_ID> --json

目标模式

当屏幕包含OCR无法自信验证的信息时，使用OCR首次桌面执行并自动回退到切换：

python desktop_mcp.py goal "Open Google and search google" --max-steps 8 --local-ocr --json

行为：

  • 使用本地OCR观察屏幕
  • 让模型决定下一个桌面操作
  • 行动后重新观察
  • 如果OCR不充分，请返回 handoff_required 带有截图包

这是推荐的模式 CC Switch 风格环境。

Gateway回退

自动回退适用于纯文本模型调用，包括：

  • goal --local-ocr
  • 本地OCR验证
  • 纯文本规划路径

网关式故障会触发回退，例如：

  • 403 / 1010
  • 5xx
  • 超时
  • 连接失败

这意味着即使主代理被临时阻止，桌面MCP也可以继续运行，同时仍然保留本地OCR和切换作为可靠的图像路径。

MCP工具

  • desktop_observe：使用本地OCR、模型分析或切换包装观察屏幕截图
  • desktop_action：运行一个桌面操作
  • desktop_goal：运行多步骤任务
  • desktop_cleanup：从切换作业中删除临时屏幕截图文件

MCP JSON-RPC运行状况检查

@'
{"jsonrpc":"2.0","id":11,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}
{"jsonrpc":"2.0","id":12,"method":"tools/list","params":{}}
'@ | python desktop_mcp.py mcp-serve

安全

  • 从低风险行动开始
  • 在发送实际输入之前确认焦点和坐标
  • pyautogui.FAILSAFE = True 已启用

许可证

MIT。看 LICENSE.

相关 MCP