DesktopBridge 🌉

Servidor local del Model Context Protocol para macOS. Claude (o cualquier host MCP) se comunica con él a través de stdio y puede:

• Leer, escribir, listar y buscar archivos dentro de directorios permitidos

• Leer estadísticas de CPU / memoria / disco, tiempo de actividad y un entorno redactado

• Listar aplicaciones en ejecución

• Ejecutar comandos de shell con stdout/stderr separados, tiempos de espera y transmisión opcional de progreso

• Leer y escribir el portapapeles

• Capturar capturas de pantalla y listar pantallas

Este proceso tiene los mismos derechos del sistema operativo que el usuario que lo inició. Trátalo como si le dieras al modelo una terminal en tu Mac, y luego reduce ese radio de impacto con DESKTOP_BRIDGE_ROOTS.

Requisitos

• macOS (portapapeles, capturas de pantalla y listado de aplicaciones usan herramientas de Apple)

• Node.js 20.19+ (se recomienda 22 LTS)

Related MCP server: macOS Automator MCP Server

Instalar

cd desktop-bridge
npm install
npm run build
npm test

El punto de entrada compilado es dist/index.js.

Conectar a Claude Desktop

1. Compila el servidor (npm run build).

2. Abre Claude Desktop → Configuración → Desarrollador → Editar configuración.

3. Fusiona el bloque de claude_desktop_config.example.json, reemplazando la ruta y los nombres de usuario:

{
  "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. Cierra y vuelve a abrir Claude Desktop por completo.

5. Confirma que desktop-bridge aparece en las herramientas MCP (icono de puente 🌉).

Archivo de configuración en macOS:

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

Conectar a Claude Code

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

O agrega el mismo bloque command / args / env a ~/.claude.json.

Conectar a Cursor

Agrega a ~/.cursor/mcp.json (o al .cursor/mcp.json del proyecto):

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

Prueba rápida sin un host

npm run inspector

Eso lanza el MCP Inspector contra el servidor stdio compilado. Llama a list_roots y luego a get_system_info.

Los registros van solo a stderr. No uses console.log en este proceso: stdout es el canal JSON-RPC.

Entorno

Copia .env.example para una plantilla comentada. El servidor lee el entorno del proceso (bloque env de Claude Desktop), no un archivo .env.

Herramientas

Recursos: desktop://roots, desktop://system/info.
Prompts: inspect_desktop, find_file.

Modelo de seguridad

• Archivos: cada ruta se resuelve con realpath. La ruta resuelta debe permanecer dentro de una raíz configurada. Se rechazan .., barras adicionales y enlaces simbólicos que escapen.

• El directorio de inicio no es una raíz predeterminada. Eso mantiene ~/.ssh y similares fuera de alcance hasta que los agregues a propósito.

• Shell: sigue siendo un shell de usuario completo. Un comando puede hacer cd a cualquier lugar incluso cuando el cwd está restringido. Deshabilítalo con DESKTOP_BRIDGE_ALLOW_SHELL=false si solo quieres herramientas de archivos/portapapeles/pantalla.

• Entorno: las claves que coinciden con password/token/secret/key/credential/cookie/session se reemplazan con [redacted].

• Stdio: sin listener de red. El host inicia este proceso.

Permisos de macOS

Si screencapture falla, abre Configuración del sistema → Privacidad y seguridad → Grabación de pantalla y habilita la aplicación host, luego reiníciala.

Desarrollo

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

Distribución: src/lib/* (guardia de rutas, ejecutor de procesos, glob/búsqueda), src/tools/* (herramientas MCP), src/index.ts (entrada stdio).

Inicio

https://home.jameymcelveen.com es la página de inicio del navegador (web/, sin paquetes npm adicionales). El inicio de sesión es @mcelveen.us más STATUS_PASSWORD.

Lo que hay hoy, y la bandeja de descarga para lo que venga después:

Establece la página de inicio de Chrome/Safari/Firefox a https://home.jameymcelveen.com (los navegadores no permiten que la página lo haga por ti). La cookie de sesión dura 30 días. / enfoca la búsqueda; ⌘K también.

Empujar a main ejecuta CI, luego despliega Vercel (el sitio) y Railway (latido + configuración guardada).

En el Mac, agrega al entorno del servidor MCP:

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

Licencia

MIT