desktop-control-mcp

一个 Windows 桌面自动化服务器，通过两个接口提供鼠标、键盘、屏幕捕获和 AI 驱动的 UI 元素检测：

• MCP 服务器（mcp_server.py）——使用 stdio 传输，专为与 Claude Code、Claude Desktop 及其他 MCP 客户端配合使用而设计

• HTTP 服务器（server.py + app.py）——一个运行在 http://localhost:7845 上的 Flask API，可从系统托盘图标启动

两个接口共享相同的底层 controller.py（Windows 自动化）和 ui_parser.py（视觉模型），因此功能完全一致。

亮点

• 基于 AI 视觉的点击——UI 元素通过 Microsoft OmniParser v2（YOLO 图标检测器 + Florence-2 描述器 + EasyOCR）检测，因此你可以按意图定位按钮/输入框，而无需根据截图猜测像素坐标。

• DPI 感知——以 PROCESS_PER_MONITOR_DPI_AWARE 方式运行，因此无论 Windows 的显示缩放如何，坐标始终是物理像素。

• 截图中的光标——真实的 Windows 光标位图通过 Win32 GDI API 合成到每张截图中，因此 AI 客户端可以看到鼠标的位置。

• 三种截图模式——单张压缩 JPEG、带标注的检测视图，以及时间分散的连拍捕获（用于观察动画或加载状态）。

• 智能键盘分发——为纯文本、单个按键和修饰键组合提供独立的工具，因此 "ctrl+c" 永远不会被误输入为文本。

Related MCP server: desktop-automation-mcp

安装

需要 Windows 和 Python 3.10+。

git clone https://github.com/ahmetdenizyilmaz/desktop-control-mcp.git
cd desktop-control-mcp
pip install -r requirements.txt

首次运行时，OmniParser v2 模型权重（约 1 GB）会从 Hugging Face 下载到本地缓存。如果安装了支持 CUDA 的 PyTorch，则会自动使用 GPU；否则使用 CPU。

运行

作为 MCP 服务器（stdio）运行

向你的 MCP 客户端配置（例如 Claude Desktop / Claude Code）添加如下条目：

{
  "mcpServers": {
    "desktop-control": {
      "command": "python",
      "args": ["C:\\path\\to\\desktop-control-mcp\\mcp_server.py"]
    }
  }
}

服务器会立即启动；模型在后台线程中加载，因此第一次 detect_ui_elements 调用会等待模型就绪，而其余工具可以立即使用。

作为带托盘图标的 HTTP 服务器运行

python app.py

会出现一个带有 Start / Stop / Quit 的托盘图标。Flask API 监听 http://localhost:7845。端点详细信息请参阅 API_DOCS.md。

MCP 工具

屏幕信息

截图

鼠标

键盘

强制点击工作流

坐标在屏幕变化后不会保持稳定——每次打开菜单、每次弹出对话框、每次滚动都会移动元素。服务器强制执行以下循环：

1. 检测——detect_ui_elements 返回当前元素表格。

2. 查找——在 Label 列中匹配你的目标。

3. 点击——使用表格中的精确 Center 坐标调用 click_mouse(x, y)。

4. 验证——调用 take_screenshot 确认点击已生效。

5. 恢复——如果点击未命中，请重新检测（屏幕可能已变化）并重试。

切勿根据原始截图猜测坐标。detect_ui_elements 返回的元素表格才是唯一依据。

示例元素表格

  ID  Type   Conf   Center         Label
   1  text   0.98   ( 499,   55)   File  Edit  View
   2  icon   0.91   ( 674,  200)   Search button
   3  icon   0.87   (1200,  400)   Close

要点击搜索按钮：click_mouse(x=674, y=200)。

HTTP API

以 app.py 方式运行时，端口 7845 上的 Flask 服务器提供与 MCP 工具对应的功能：

完整的请求/响应模式见 API_DOCS.md。

文件布局

mcp_server.py          FastMCP server — tool definitions and lifespan
controller.py          Win32 / pyautogui / mss core — screenshots, input, window info
ui_parser.py           OmniParser v2 loading + UI detection + image annotation
screenshot_manager.py  Disk-side screenshot cache (cleanup, naming, burst dirs)
overlay.py             On-screen overlay utilities
lock_manager.py        Concurrency lock for shared resources
server.py              Flask HTTP API
app.py                 Tray-icon launcher for the Flask server
templates/index.html   Web UI for the Flask server
requirements.txt       Python dependencies
API_DOCS.md            HTTP endpoint reference
run_agents.bat         Convenience launcher for Claude Code in this folder

平台说明

• 仅支持 Windows。 光标合成、DPI 感知和活动窗口相关代码直接使用 Win32 API。

• 仅支持主显示器。 所有坐标都在主显示器的像素空间中。

• 首次检测较慢。 OmniParser 模型加载 + EasyOCR 初始化在首次调用时可能需要 30–60 秒。后续检测很快（GPU 上低于 1 秒，CPU 上几秒）。