desktop-mcp

Десктопное зрение и управление для LLM на Linux, включая Wayland — модель делает скриншот всего экрана и кликает, печатает и прокручивает то, что видит. Обычный MCP через stdio, поэтому работает в Claude Code, Claude Desktop, Cursor или любом другом MCP-клиенте.

Прочтите сначала: возможно, это вам не нужно

Anthropic поставляет computer use нативно, и там, где это работает, лучше использовать его — он лучше интегрирован и реально поддерживается:

• macOS и Windows: в Claude Desktop есть встроенный computer use, в Cowork и Claude Code. Он управляет вашим реальным рабочим столом. (документация)

• Создание собственного агента: в Claude API есть первоклассный инструмент computer (GA как набор computer_toolset_20260801). (документация)

Пробел, который заполняет этот проект, — Linux. По состоянию на август 2026 года computer use недоступен в десктопном приложении Linux, а автоматизация рабочего стола на Wayland действительно неудобна так, как никогда не была на X11:

• Композитор COSMIC не реализует wlr-screencopy, поэтому grim полностью не работает, и каждому инструменту создания скриншотов нужен свой путь для каждого композитора.

• Нет протокола для запроса позиции курсора и нет способа перечислить окна другого клиента.

• Ввод должен идти ниже композитора через /dev/uinput, потому что обычно упакованный ydotool предоставляет относительный указатель, чьи длинные прыжки искажаются ускорением указателя.

Если вы на macOS или Windows, этот репозиторий в основном избыточен. Если вы на Linux — особенно на Wayland — это рабочий вариант.

MCP-серверы для автоматизации рабочего стола — не новая категория; существуют тысячи MCP-серверов. Что здесь специфично, так это нативный для Wayland путь ввода через абсолютный uinput, измеренный с точностью до пикселя на COSMIC.

Related MCP server: mcp-linux-desktop

Статус

Написан кроссплатформенно, но реально проверена только одна конфигурация. Остальное — это пути кода, а не доказательства; относитесь к этому соответственно.

Что было протестировано и как

Проверено end-to-end на:

• Pop!_OS 24.04 LTS, ядро 7.0.11, COSMIC (cosmic-comp 1.0.0), Wayland, один дисплей 2560x1440, Python 3.13.

Результаты:

Не протестировано и стоит знать: многомониторные конфигурации, масштабирование HiDPI, не-US раскладки клавиатуры на пути сырых кодов клавиш (wtype обрабатывает их корректно; коды клавиш uinput предполагают US), и все композиторы, кроме COSMIC.

Отчёты с других платформ приветствуются — desktop_info выводит всё необходимое для диагностики проблемы с бэкендом.

Установка

git clone <this repo> && cd desktop-mcp
uv venv && uv pip install -e .

Для macOS, Windows и Linux/X11 также нужны зависимости для ввода:

uv pip install -e ".[gui]"

Linux: разовая настройка разрешений

Ввод на Wayland означает запись в /dev/uinput, который по умолчанию принадлежит root:

bash scripts/setup-linux.sh   # needs sudo once
# then log out and back in

macOS: разовая настройка разрешений

Предоставьте Запись экрана и Специальные возможности приложению, которое запускает сервер (Terminal, iTerm, Claude Desktop) в Системные настройки → Конфиденциальность и безопасность.

Подключение

Claude Code:

claude mcp add desktop -- /absolute/path/to/desktop-mcp/.venv/bin/python -m desktop_mcp.server

Claude Desktop (claude_desktop_config.json) и Cursor (.cursor/mcp.json) используют ту же форму:

{
  "mcpServers": {
    "desktop": {
      "command": "/absolute/path/to/desktop-mcp/.venv/bin/python",
      "args": ["-m", "desktop_mcp.server"]
    }
  }
}

Инструменты

Координаты

Скриншоты уменьшаются (по умолчанию длинная сторона 1400px) перед отправкой, поэтому модель работает в пикселях изображения; сервер преобразует их обратно в пиксели экрана при каждом вызове. Передавайте ровно те координаты, которые вы считали со скриншота.

Это деталь, которую большинство самодельных инструментов computer use делают неправильно. Упустите её — и каждый клик будет попадать в постоянную долю от цели.

Почему /dev/uinput вместо ydotool на Linux

Обычно упакованные сборки ydotool предоставляют относительный указатель, поэтому прыжок к (1280, 720) доставляется как одно большое относительное движение — которое композитор пропускает через ускорение указателя. Курсор оказывается рядом с целью, а не на ней, и ошибка растёт с расстоянием. Абсолютное устройство uinput обходит ускорение: измерено 5/5 точно на экране 2560x1440. ydotool остаётся запасным вариантом, когда /dev/uinput недоступен для записи.

Тайминг кликов

Композиторы обрабатывают движение указателя асинхронно, а тулкиты игнорируют нажатие кнопки, которое приходит до того, как они обработали движение, поместившее курсор над виджетом. Измерено на COSMIC: задержка 30 мс между движением и нажатием надёжно подсвечивает кнопку, но никогда не активирует её — состояние наведения доказывает, что координаты верны, что позволяет легко ошибочно принять эту ошибку за проблему с прицеливанием. 250 мс активирует её. Нажатие также должно удерживаться (~90 мс), чтобы зарегистрироваться как реальный клик, а не случайное событие.

Обе задержки настраиваются; уменьшайте их только если ваш рабочий стол это терпит.

Безопасность

Это даёт модели тот же доступ к машине, что и сидящему за ней человеку. Она может читать всё на экране — открытые менеджеры паролей, личные сообщения, токены — и кликать по чему угодно, включая разрушительные кнопки. Относитесь к сессии так, как если бы вы передали кому-то свою клавиатуру.

Переменные окружения:

ctrl+alt+F1–F12 всегда заблокированы; переключение виртуальных терминалов может выбить графическую сессию из-под вас.

Настройка для рецензента только для чтения:

DESKTOP_MCP_READ_ONLY=1 python -m desktop_mcp.server

Проверка

.venv/bin/python scripts/mcp_smoke.py   # real stdio MCP round trip