Skip to main content
Glama
desktop-control-mcp

desktop-control-mcp

desktop-control-mcp

Claude Desktop Controller 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 工具

屏幕信息

工具

描述

get_screen_size()

主显示器分辨率。调用一次以了解坐标空间。

get_active_window()

当前焦点窗口的标题、位置和大小。

截图

工具

描述

take_screenshot(quality=30)

主显示器的压缩 JPEG。仅用于观察——不要从中推导坐标。

detect_ui_elements(confidence_threshold=0.5, full_response=False)

运行 OmniParser + EasyOCR,返回一张带标注的图像,以及每个检测元素的 (id, type, confidence, center, label) 表格。这就是你找到要点击坐标的方法。

take_screenshot_burst(frame_count=10, duration_seconds=1.0)

在指定时长内均匀捕获 N 帧。适用于动画、加载指示器或对时序敏感的 UI。

鼠标

工具

描述

click_mouse(x, y, button="left")

单击。始终使用来自 detect_ui_elements 的坐标。

double_click(x, y)

双击。

move_mouse(x, y)

移动光标而不点击。

drag_mouse(x1, y1, x2, y2, button="left")

点击并拖动。

scroll(x, y, direction, amount=3)

在指定位置滚动滚轮(up/down/left/right)。

键盘

工具

使用时机

type_text(text)

纯文本输入(文件名、搜索查询、URL、代码)。永远不会把 + 解释为快捷键。

press_key(key, presses=1)

单个命名按键(enter、tab、escape、f5、方向键、delete 等)。

send_keys(text)

仅用于修饰键+按键组合(ctrl+c、alt+tab、win+d、ctrl+shift+s)。


强制点击工作流

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

  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 工具对应的功能:

端点

用途

GET /health

存活检查。

POST /screenshot

返回屏幕的 base64 PNG。

POST /move

{x, y}——移动光标。

POST /click

{x, y, button?}——点击。

POST /keys

{keys}——文本或快捷键(自动检测)。

POST /command

单条方括号命令,如 [ClickMouse(500,300)]。

POST /actions

按顺序执行的方括号命令列表,命令之间可选用 delay 间隔。

完整的请求/响应模式见 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 上几秒)。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server that provides computer control capabilities including mouse movements, keyboard actions, screenshot capture with OCR, and window management through a unified API.
      549 PyPI
      176
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for driving any Windows app through five layers including OCR, UI Automation, and direct OS operations. Enables AI agents to control Windows desktop and OS cursor-free, even on background/locked windows.
      77 npm
      3
      MIT