DesktopBridge 🌉

Локальный сервер Model Context Protocol для macOS. Claude (или любой MCP-хост) общается с ним через stdio и может:

• Читать, записывать, перечислять и искать файлы в разрешённых каталогах

• Читать статистику CPU / памяти / диска, время работы и урезанное окружение

• Перечислять запущенные приложения

• Выполнять команды оболочки с раздельными stdout/stderr, таймаутами и опциональной потоковой передачей прогресса

• Читать и записывать буфер обмена

• Делать скриншоты и перечислять дисплеи

Этот процесс имеет те же права ОС, что и пользователь, который его запустил. Относитесь к нему как к предоставлению модели терминала на вашем Mac, а затем уменьшите радиус поражения с помощью DESKTOP_BRIDGE_ROOTS.

Требования

• macOS (буфер обмена, скриншоты и список приложений используют инструменты Apple)

• Node.js 20.19+ (рекомендуется 22 LTS)

Related MCP server: macOS Automator MCP Server

Установка

cd desktop-bridge
npm install
npm run build
npm test

Скомпилированная точка входа — dist/index.js.

Подключение к Claude Desktop

1. Соберите сервер (npm run build).

2. Откройте Claude Desktop → Settings → Developer → Edit Config.

3. Объедините блок из claude_desktop_config.example.json, заменив путь и имена пользователей:

{
  "mcpServers": {
    "desktop-bridge": {
      "command": "node",
      "args": ["/Users/YOU/dev/desktop-bridge/dist/index.js"],
      "env": {
        "DESKTOP_BRIDGE_ROOTS": "/Users/YOU/Desktop,/Users/YOU/Documents,/Users/YOU/Downloads"
      }
    }
  }
}

4. Полностью выйдите и снова откройте Claude Desktop.

5. Подтвердите, что desktop-bridge появился в MCP-инструментах (значок моста 🌉).

Файл конфигурации на macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Подключение к Claude Code

claude mcp add desktop-bridge -- node /Users/YOU/dev/desktop-bridge/dist/index.js

Или добавьте тот же блок command / args / env в ~/.claude.json.

Подключение к Cursor

Добавьте в ~/.cursor/mcp.json (или в проектный .cursor/mcp.json):

{
  "mcpServers": {
    "desktop-bridge": {
      "command": "node",
      "args": ["/Users/YOU/dev/desktop-bridge/dist/index.js"]
    }
  }
}

Быстрая проверка без хоста

npm run inspector

Это запускает MCP Inspector для собранного stdio-сервера. Вызовите list_roots, затем get_system_info.

Логи идут только в stderr. Не используйте console.log в этом процессе — stdout является каналом JSON-RPC.

Окружение

Скопируйте .env.example для шаблона с комментариями. Сервер читает переменные окружения процесса (блок env в Claude Desktop), а не файл .env.

Инструменты

Ресурсы: desktop://roots, desktop://system/info.
Промпты: inspect_desktop, find_file.

Модель безопасности

• Файлы: каждый путь проходит через realpath. Разрешённый путь должен оставаться внутри настроенного корня. .., лишние слэши и симлинки, ведущие наружу, отклоняются.

• Домашний каталог не является корнем по умолчанию. Это держит ~/.ssh и подобное вне досягаемости, пока вы не добавите их намеренно.

• Оболочка: всё ещё полная пользовательская оболочка. Команда может cd куда угодно, даже если cwd ограничен. Отключите её с помощью DESKTOP_BRIDGE_ALLOW_SHELL=false, если нужны только файловые/буферные/экранные инструменты.

• Окружение: ключи, соответствующие password/token/secret/key/credential/cookie/session, заменяются на [redacted].

• Stdio: нет сетевого слушателя. Хост запускает этот процесс.

Разрешения macOS

Если screencapture не работает, откройте System Settings → Privacy & Security → Screen Recording и включите хост-приложение, затем перезапустите его.

Разработка

npm run build    # tsc → dist/
npm start        # node dist/index.js (stdio)
npm test         # compile + node:test

Структура: src/lib/* (защита путей, запуск процессов, glob/поиск), src/tools/* (MCP-инструменты), src/index.ts (stdio-вход).

Домашняя страница

https://home.jameymcelveen.com — стартовая страница браузера (web/, без дополнительных npm-пакетов). Вход — @mcelveen.us плюс STATUS_PASSWORD.

Что есть сегодня, и лоток для всего, что появится дальше:

Установите домашнюю страницу Chrome/Safari/Firefox на https://home.jameymcelveen.com (браузеры не позволят странице сделать это за вас). Сессионный cookie действует 30 дней. / фокусирует поиск; ⌘K тоже.

Пуш в main запускает CI, затем разворачивает Vercel (сайт) и Railway (heartbeat + сохранённая конфигурация).

На Mac добавьте в env MCP-сервера:

DESKTOP_BRIDGE_STATUS_URL=https://home.jameymcelveen.com/api/heartbeat
DESKTOP_BRIDGE_STATUS_TOKEN=<HEARTBEAT_TOKEN>

Лицензия

MIT