Command-Line MCP Server

Un servidor remoto Model Context Protocol que expone una única herramienta, run_command, que permite a Claude (a través de la función Connectors de Claude Desktop) ejecutar comandos de shell en la máquina que ejecuta este servidor.

El servidor implementa OAuth 2.1 (Dynamic Client Registration + PKCE) porque los conectores de Claude Desktop requieren un handshake OAuth — un conector sin servidor de autenticación es rechazado al iniciar sesión. Este servidor auto-aprueba la autorización (sin prompt de usuario), lo cual es adecuado para un servidor personal expuesto a través de un túnel.

⚠️ Advertencia de seguridad: Cualquiera que pueda alcanzar este servidor y completar el flujo OAuth (automático) puede ejecutar comandos arbitrarios como el usuario que lo ejecuta. Solo expóngalo a través de un túnel privado (cloudflared / ngrok) y nunca en una red pública.

Cómo funciona

• Transporte: Streamable HTTP (el transporte que requieren los conectores de Claude Desktop).

• Sin estado: cada solicitud crea una nueva instancia de servidor/transporte (no se necesita almacén de sesiones).

• Endpoint: POST /mcp

• Health check: GET /health

Herramientas

run_command

Ejecuta un comando de shell. En Windows, el shell predeterminado es cmd.exe (use dir, cd, no ls/pwd) a menos que pase shell: "powershell".

get_info

Devuelve el sistema operativo, la arquitectura, el shell predeterminado (cmd.exe en Windows) y el directorio de trabajo actual — llámelo una vez para que el cliente sepa qué shell usar.

read_file

Lee un archivo de texto (rango de líneas opcional offset/limit). path es absoluto o relativo al cwd.

list_files

Lista un directorio. recursive: true recorre el árbol (limitado a profundidad 4).

edit_file

Reemplazo exacto de cadena — la forma preferida de editar código (sin necesidad de escape de shell). path, old_text, new_text, replace_all opcional. old_text debe ser único a menos que se establezca replace_all. Devuelve un diff corto.

apply_patch

Aplica un diff unificado mediante git apply (con un fallback --3way). cwd = raíz del repositorio, patch = texto del diff.

write_file

Escribe contenido completo en un archivo (overwrite, o append).

batch_read

Lee varios archivos en una sola llamada. files: array de { path, offset?, limit? }.

batch_edit

Aplica muchas ediciones de texto exacto en uno o más archivos en una sola llamada. Transaccional: cada old_text se valida antes de escribir cualquier archivo, por lo que una coincidencia faltante/ambigua aborta todo el lote (no cambia nada). Cada edición: { path, old_text, new_text, replace_all? }.

Paso directo de git nativo

git_status (-sb), git_diff (opciones staged + paths), git_log (max_count, revision), git_show (revision). Cada uno acepta un cwd opcional.

Todas las rutas de archivo se resuelven en el host que ejecuta el servidor — apuntan a esta máquina, no al sandbox de Claude.

Ejecutar localmente

npm install
npm start
# server listens on http://localhost:3000/mcp

Variables de entorno opcionales: PORT, CMD_TIMEOUT_MS, CMD_MAX_BUFFER.

npm start ejecuta start.js, que libera el puerto 3000 (mata cualquier proceso que lo tenga) antes de lanzar el servidor, para que nunca encuentre EADDRINUSE.

Exponerlo a Claude Desktop

Opción A — Cloudflare Worker (URL estable, sin trycloudflare, sin dominio necesario)

Un agente local pequeño mantiene un WebSocket abierto hacia un Cloudflare Worker, que se convierte en su endpoint público estable *.workers.dev para MCP. El Worker solo retransmite a su máquina mientras el agente (autenticado con PROXY_SECRET) esté conectado.

1. wrangler login (cuenta gratuita de Cloudflare).

2. Desplegar: wrangler deploy → anote su URL, p. ej. https://command-line-mcp.<subdomain>.workers.dev.

3. Establezca el secreto (el mismo valor que ya está en su .dev.vars ignorado por git): wrangler secret put PROXY_SECRET (pegue el PROXY_SECRET de .dev.vars).

4. Apunte el agente al Worker desplegado: establezca WORKER_URL en .dev.vars a esa URL.

5. En su máquina, ejecute ambos:

   npm start          # the MCP server on :3000
   npm run agent      # connects to the Worker with the secret

6. En Claude Desktop: Customize → Connectors → Add custom connector, pegue https://command-line-mcp.<subdomain>.workers.dev/mcp.

Pruebas locales sin desplegar: wrangler dev --port 8787 (Worker en :8787), luego npm run agent — el agente lee WORKER_URL de .dev.vars.

Opción B — Túnel cloudflared / ngrok (URL efímera)

Los conectores de Claude Desktop necesitan una URL HTTPS, así que ejecute el servidor localmente y túnel:

cloudflared tunnel --url http://localhost:3000 --protocol http2
# or: ngrok http 3000

Copie la URL https://… generada y añada /mcp, p. ej. https://abc-123.trycloudflare.com/mcp.

Añadir a Claude Desktop

1. Abra Customize → Connectors → Add custom connector.

2. Pegue la URL (con /mcp), p. ej. la URL del Worker de la Opción A.

3. Nómbrelo Command-Line.

4. Guarde. Claude descubre los metadatos OAuth, registra un cliente y abre un navegador hacia el endpoint de autorización (auto-aprobación), luego redirige de vuelta y está listo. No es necesario introducir manualmente un "OAuth Client ID" — DCR lo maneja.

Pruebas sin Claude

Use el MCP Inspector:

npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP, URL: http://localhost:3000/mcp

Endurecimiento (para uso no personal)

OAuth ya está implementado (ver oauthProvider.js). Para cualquier cosa más allá de un túnel personal debería:

1. Reemplazar el authorize() de auto-aprobación con una pantalla de consentimiento real, o al menos un conjunto de URIs de redirección / clientes en lista blanca.

2. Persistir clientes/tokens (actualmente en memoria — se reinician al reiniciar).

3. Alojar detrás de un dominio HTTPS estable (p. ej. un VPS, Cloudflare Workers, Fly.io).

4. Considerar una lista blanca de comandos permitidos para limitar el radio de explosión.

Licencia

MIT