nuphus-mcp

MCP-сервер для автоматизации рабочего стола — компьютерное использование для любого ИИ-агента. Видит экран, управляет окнами/мышью/клавиатурой и управляет Chrome через Model Context Protocol (stdio). Для автоматизации рабочего стола и браузера не требуется API-ключ; OCR работает локально; зрение подключается к вашей собственной vision-LLM (совместимой с OpenAI или нативной Anthropic, BYOK).

nuphus-mcp — это легковесный, кроссплатформенный MCP-сервер для автоматизации рабочего стола, который предоставляет автоматизацию рабочего стола и браузера в виде стандартных MCP-инструментов. Он работает через JSON-RPC 2.0 поверх stdio — без демона, без сетевого сервиса, один бинарный файл. Claude Desktop, Cursor, VS Code, Copilot или любой MCP-клиент может подключиться и сразу управлять экраном, окнами, клавиатурой/мышью и Chrome — компьютерное использование для любого ИИ-агента — для автоматизации рабочего стола и браузера не требуется API-ключ; встроен локальный OCR; зрение работает с вашей собственной vision-LLM (совместимой с OpenAI, BYOK).

🇨🇳 Зеркало для материкового Китая: этот репозиторий зеркалируется на Gitee для быстрого доступа из Китая (там по умолчанию отображается китайская документация). 中文文档

┌──────────────────┐   stdio JSON-RPC   ┌──────────────────────┐
│  Any MCP Client  │  ───────────────►  │      nuphus-mcp      │
│  (Claude/Cursor/ │  ◄───────────────  │  desktop-api crate   │──► screen/window/mouse/keyboard
│   Nuphus itself) │  single-line JSON  │  nuphus-browser crate│──► Chrome (CDP)
└──────────────────┘                    └──────────────────────┘

Возможности

• 38 MCP-инструментов (15 для рабочего стола + 23 для браузера) — скриншоты, управление окнами, мышь/клавиатура, Chrome CDP-автоматизация и многое другое — полный справочник см. в TOOLS.md / TOOLS.zh-CN.md.
• Автоматизация рабочего стола: размер экрана, скриншот (PNG/base64), список окон, активация/скриншот/перемещение/изменение размера/информация об окне, клик/перетаскивание/прокрутка/позиция мыши, ввод с клавиатуры/горячие клавиши, запись/очистка буфера обмена — реализовано на крейте desktop-api (xcap + Win32, без зависимости от Tauri).
• Пара компьютерного зрения: desktop_vision (BYOK — отправка скриншота в вашу собственную vision-модель через API, совместимое с OpenAI или нативное Anthropic) + desktop_perceive (локальный OCR с PaddleOCR, модели автоматически загружаются при первом запуске; опционально обнаружение значков YOLO). При совместном использовании они дают ИИ-агентам как семантическое понимание, так и попиксельно точные координаты — проверенный боевыми условиями поток vision→perceive из настольного приложения Nuphus. См. TOOLS.md для переменных окружения BYOK, настройки модели и рекомендуемого потока.
• Автоматизация браузера: навигация, снимок (дерево доступности со ссылками @N), клик, ввод, выполнение, прокрутка, извлечение, скриншот, оценка, назад/вперёд, ожидание, получение/установка/импорт cookie, загрузка, вкладки, загрузки — реализовано на nuphus-browser (chromiumoxide CDP).
• Бесплатный stdio: без HTTP-сервера, без демона. Процесс читает однострочный JSON из stdin и записывает ответы в stdout.
• Безопасность прежде всего: разрушительные инструменты аннотированы в соответствии со спецификацией MCP; опциональный режим строгого подтверждения; проверка путей для скриншотов, загрузок и перетаскивания файлов.

Структура репозитория

nuphus-mcp/
├── Cargo.toml                  # workspace root
├── TOOLS.md / TOOLS.zh-CN.md   # 38-tool reference
├── crates/
│   ├── nuphus-mcp/             # MCP Server (this repo's product)
│   ├── nuphus-browser/         # Browser automation core (CDP)
│   └── desktop-api/            # Desktop control core (vendored)
└── ...

Предварительные требования

• Инструментарий Rust (стабильный) — сборка из исходного кода с помощью Cargo.
• Chrome или Edge — требуется для браузерных инструментов. Сервер автоматически обнаруживает установленный браузер; если он не найден, инструменты browser_* возвращают понятную ошибку.
• Windows рекомендуется для полного управления рабочим столом — см. Поддержку платформ ниже.

Поддержка платформ

API-ключи и локальные модели

Зрение — BYOK, совместимое с OpenAI или нативное Anthropic

desktop_vision использует вашу собственную vision-модель. Он поддерживает два протокола: - Совместимый с OpenAI Chat Completions (по умолчанию) — работает с OpenAI, MiniMax, Qwen, Ollama, vLLM, … - Нативный Anthropic Messages API — укажите NUPHUS_MCP_VISION_BASE_URL на https://api.anthropic.com/v1, и протокол будет автоматически определён по хосту; или принудительно задайте NUPHUS_MCP_VISION_PROVIDER=anthropic.

Ничего не требуется, если вы не вызываете этот инструмент — а если он не настроен, инструмент возвращает понятную ошибку вместо тихого сбоя.

Внешний браузер (антидетект / браузеры с отпечатками)

По умолчанию инструменты browser_* запускают и управляют собственным экземпляром Chrome. Чтобы управлять внешним браузером — например, антидетект-браузером или браузером с отпечатками — запустите его с отладочным портом и укажите серверу на него:

# Example: start your fingerprint browser with a debugging port
chrome --remote-debugging-port=9222 --user-data-dir=...

// MCP client config
"env": { "NUPHUS_MCP_BROWSER_CDP_URL": "http://127.0.0.1:9222" }

При заданном значении инструменты browser_* подключаются к этой конечной точке и никогда не запускают управляемый Chrome; ошибки подключения являются критическими (без тихого переключения на неправильный браузер). Внешний браузер принадлежит вам — сервер никогда не завершает его при выходе.

Самовосстановление при повторном открытии окна (рекомендуется)

Антидетект-браузеры обычно получают новый случайный отладочный порт при каждом повторном открытии окна, из-за чего фиксированный ..._CDP_URL будет указывать на неработающий порт. Укажите идентичность браузера — и сервер автоматически определит актуальный порт при следующем вызове инструмента:

// MCP client config — attach + self-heal
"env": {
  "NUPHUS_MCP_BROWSER_CDP_URL": "http://127.0.0.1:9222",
  "NUPHUS_BROWSER_EXE_PATH": "C:\\path\\to\\fingerprint-browser.exe",
  "NUPHUS_BROWSER_NAME": "AdsPower",
  "NUPHUS_BROWSER_USER_DATA_DIR": "C:\\path\\to\\profile"
}

С заданной идентичностью, если настроенная конечная точка перестаёт отвечать, сервер находит процесс окна по пути к исполняемому файлу, заново определяет его фактический порт (буквальный порт из командной строки или DevToolsActivePort в каталоге профиля для запусков со случайным портом), проверяет кандидата с помощью CDP-пробы, обходящей прокси, и повторяет попытку один раз — закройте и снова откройте окно, и следующий вызов инструмента просто сработает. Без указания идентичности ошибки подключения остаются критическими и требуют обновления настроенного URL. В любом случае переключения на управляемый Chrome не происходит.

Сохранение входов в систему: управление браузером с вашими расширениями и сессиями

Хотите, чтобы инструменты browser_* управляли браузером с вашими расширениями / закладками / состоянием входа? Во-первых, жёсткое ограничение Chrome 136+: после официального изменения безопасности Chrome, --remote-debugging-port и --remote-debugging-pipe игнорируются для каталога пользовательских данных по умолчанию — их необходимо сочетать с --user-data-dir, указывающим на нестандартный каталог. Это осознанное решение для защиты от вредоносных программ-стилеров, читающих реальные cookie через локальный отладочный порт — это не дефект nuphus-mcp, и никакие флаги / политики реестра не могут это обойти (RemoteDebuggingAllowed лишь разрешает/запрещает переключатели; он не может повторно включить их для каталога по умолчанию).

Таким образом, «реальный профиль по умолчанию + управление через CDP» взаимоисключаемы начиная с 136+. Выберите один из следующих вариантов в порядке приоритета:

Вариант A (рекомендуется, самый простой): войдите один раз в управляемый nuphus-профиль

nuphus-mcp по умолчанию управляет собственным экземпляром Chrome (выделенный --user-data-dir, всегда отлаживаемый). Откройте его, войдите один раз на сайты, где нужно оставаться авторизованным — состояние сохраняется в этом профиле, и все последующие вызовы browser_* будут нести эти сессии. Ноль настройки, ноль копирования.

Вариант B: скопируйте реальный профиль в отлаживаемый каталог (сохраняет расширения / закладки / входы)

Когда нужны расширения и состояние входа исходного браузера, скопируйте реальный профиль и запустите браузер из копии:

1. Полностью закройте запущенный Chrome / Edge (конфликт блокировки профиля)
2. Скопируйте профиль в нестандартный каталог:
   • Windows: copy "%LOCALAPPDATA%\Google\Chrome\User Data\Default" <назначение>\Default
   • macOS: cp -R ~/Library/"Application Support"/Google/Chrome/Default <назначение>/Default
   • Linux: cp -R ~/.config/google-chrome/Default <dest>/Default
3. Запустите копию с отладочным портом: chrome --remote-debugging-port=9222 --user-data-dir=<dest>
4. Подключитесь как внешний браузер: NUPHUS_MCP_BROWSER_CDP_URL=http://127.0.0.1:9222 (добавьте NUPHUS_BROWSER_EXE_PATH / NUPHUS_BROWSER_USER_DATA_DIR для самовосстановления порта)

Примечания: в Windows cookies/пароли зашифрованы на уровне пользователя через DPAPI и корректно расшифровываются из копии под тем же пользователем — состояние входа в основном сохраняется; в macOS некоторые учётные данные хранятся в Keychain, и некоторые сайты могут попросить войти снова. Копия может занимать сотни МБ или гигабайты, и она не может работать одновременно с реальным браузером.

Вариант C: визуальная автоматизация рабочего стола — управление реально запущенным окном браузера

Для управления текущим реальным браузером пользователя (доступ на уровне DOM невозможен), используйте цепочку OCR рабочего стола + мышь/клавиатура (инструменты desktop_perceive / desktop_*) — визуально кликайте, вводите текст и читайте экран без CDP, ценой отсутствия доступа к DOM и невозможности внедрения состояния входа.

Модели восприятия (локальные, автоматически загружаемые)

desktop_perceive запускает PaddleOCR и обнаружение иконок YOLO локально через ONNX Runtime. Первый вызов автоматически загружает модели OCR и icon_detect.onnx в %APPDATA%\Nuphus\models (или NUPHUS_MODELS_DIR). Сбои загрузки возвращают понятную ошибку с ручными инструкциями. YOLO необязателен во время выполнения: если его загрузка не удалась, perceive всё равно возвращает элементы OCR и сообщает yolo_available: false (используйте NUPHUS_MCP_YOLO_MODEL_URL для пользовательского источника). См. TOOLS.md → Vision & Local Models.

Все остальные инструменты не требуют ключа API.

Установка и запуск

Установка через npm (рекомендуется — все платформы, готовые бинарные файлы):

npm install -g @nuphus/nuphus-mcp

Метапакет nuphus-mcp автоматически устанавливает готовый бинарный файл для вашей платформы (Windows x64/arm64, macOS arm64, Linux x64/arm64) и добавляет команду nuphus-mcp в PATH. Инструментарий Rust не требуется:

nuphus-mcp   # stdio MCP server

Сборка из исходников (требуется инструментарий Rust):

cargo build --release -p nuphus-mcp
# binary at target/release/nuphus-mcp(.exe)

Сервер читает JSON, разделённый переводами строк, из stdin и записывает ответы JSON-RPC в stdout. Логи идут в stderr.

# quick smoke test
echo '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test"}}}' | nuphus-mcp

🔒 Рекомендуется: включить строгое подтверждение

Этот сервер может физически управлять машиной, на которой работает. По умолчанию инструменты записи выполняются без подтверждения; настоятельно рекомендуем включить строгое подтверждение, чтобы деструктивные операции требовали явного аргумента "confirm": true от клиента (иначе инструмент отклоняется с isError).

Любой из следующих способов:

# CLI flag
nuphus-mcp --confirm-write

# Environment variable (recommended — survives across clients, keeps config simple)
export NUPHUS_MCP_CONFIRM_WRITE=1      # macOS / Linux
setx NUPHUS_MCP_CONFIRM_WRITE 1        # Windows (persistent for new shells)

# MCP client args
"args": ["--confirm-write"]

Claude Desktop — рекомендуемый claude_desktop_config.json:

{
  "mcpServers": {
    "nuphus-mcp": {
      "command": "nuphus-mcp",
      "args": ["--confirm-write"]
    }
  }
}

Предпочтительнее переменная окружения: одна настройка применяется ко всем MCP-клиентам на машине. См. SECURITY.md и раздел Safety Annotations в TOOLS.md для полной модели угроз.

Конфигурация MCP-клиента

Укажите любой MCP-клиент на nuphus-mcp. После npm install -g @nuphus/nuphus-mcp команда будет в PATH; в противном случае используйте абсолютный путь к бинарному файлу (nuphus-mcp / nuphus-mcp.exe).

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "nuphus-mcp": {
      "command": "nuphus-mcp",
      "args": []
    }
  }
}

Любой MCP-клиент (общий JSON mcpServers):

{
  "mcpServers": {
    "nuphus-mcp": {
      "command": "nuphus-mcp",
      "args": [],
      "env": {}
    }
  }
}

Поддерживаемые методы MCP: initialize, notifications/initialized, ping, tools/list, tools/call.

DeepSeek Harness (DSH)

Рекомендуется — установите официальный плагин dsh-nuphus-mcp (зеркало Gitee: gitee.com/nuphus/dsh-nuphus-mcp). Он подключает nuphus-mcp в DSH как нативные инструменты с нулевой конфигурацией — --confirm-write включён по умолчанию, изменения кода не требуются:

npx -p @deepseek-ai/dsh dsh plugin --profile web add github:mrpulor-gh/dsh-nuphus-mcp

Ручная альтернатива — подключите к DeepSeek Harness как обычный stdio MCP-сервер через встроенный MCP-клиент (@deepseek-ai/dsh-mcp-client). Монтируйте в cordis.yml / патч DSH:

- id: nuphus-mcp
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: nuphus-mcp
    transport: stdio
    command: nuphus-mcp
    args: ["--confirm-write"]
    toolCallTimeoutMs: 120000   # DSH default 60000 is too low for screenshots/OCR

Инструменты регистрируются как mcp__nuphus-mcp__* (например, mcp__nuphus-mcp__desktop_click). Запустите DSH в сессии рабочего стола машины, которую нужно контролировать.

Демо

Автономный stdio-клиент, проходящий по шагам initialize → tools/list → tools/call:

cargo build -p nuphus-mcp
cargo run -p nuphus-mcp --example demo

Тесты

cargo check --workspace
cargo test -p nuphus-mcp          # protocol + security + vision + models tests (60)

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

Этот сервер может физически управлять машиной, на которой он запущен. Перед развертыванием прочтите SECURITY.md и раздел «Аннотации безопасности» из TOOLS.md. Рекомендуется запускать с флагом --confirm-write (или NUPHUS_MCP_CONFIRM_WRITE=1), чтобы инструменты записи требовали явного аргумента "confirm": true.

Лицензия

MIT