desktop-control-mcp

Сервер автоматизации рабочего стола Windows, который предоставляет управление мышью, клавиатурой, захват экрана и определение элементов интерфейса на основе ИИ через два интерфейса:

• MCP-сервер (mcp_server.py) — транспорт stdio, предназначен для использования с Claude Code, Claude Desktop и другими MCP-клиентами

• HTTP-сервер (server.py + app.py) — Flask API на http://localhost:7845, запускаемый из значка в системном трее

Оба интерфейса используют одни и те же базовые модули controller.py (автоматизация Windows) и ui_parser.py (модели компьютерного зрения), поэтому возможности идентичны.

Ключевые возможности

• Клики на основе ИИ-зрения — элементы интерфейса определяются с помощью Microsoft OmniParser v2 (детектор значков YOLO + подпись Florence-2 + EasyOCR), поэтому вы можете нацеливаться на кнопки и поля по их назначению, а не угадывать пиксельные координаты по скриншоту.

• Учет DPI — работает как PROCESS_PER_MONITOR_DPI_AWARE, поэтому координаты всегда соответствуют физическим пикселям независимо от масштабирования дисплея Windows.

• Курсор на скриншотах — реальный курсор Windows встраивается в каждый скриншот через Win32 GDI API, чтобы ИИ-клиенты могли видеть, где находится мышь.

• Три режима скриншотов — одиночный сжатый 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 ГБ) загружаются с Hugging Face в локальный кэш. GPU используется автоматически, если установлен PyTorch с поддержкой CUDA; в противном случае используется 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. КЛИКНИТЕ — click_mouse(x, y) с точными координатами Center из таблицы.

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 Flask-сервер на порту 7845 повторяет 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, несколько секунд на CPU).