ftp-deploy-mcp

El botón de implementación para agentes de codificación de IA. Claude Code · Claude Desktop · Cursor · Windsurf · Trae · Antigravity → tus propios servidores FTP / FTPS / SFTP.

Versión francesa → README.fr.md

Tu agente ejecuta el despliegue: tú solo pides.

Por qué

• Todo proyecto web termina igual: "ahora súbelo al servidor".

• Los agentes de IA escriben buen código, pero la mayoría no tiene una forma segura de publicarlo en un alojamiento clásico: OVH, Ionos, Hostinger, o2switch y el resto del mundo del alojamiento compartido siguen funcionando con FTP/SFTP, no con git push.

• ftp-deploy-mcp ofrece a cualquier cliente MCP una vía de despliegue hacia tu propia infraestructura, en la misma conversación donde se escribió el código.

• A diferencia de los servidores MCP genéricos de ejecución SSH, este está diseñado específicamente para el despliegue de archivos: un aislamiento de ruta (path jail), un modo de solo lectura, simulación (dry-run) y credenciales que nunca entran en el contexto del modelo.

Related MCP server: mcp-remote-ssh

Características

Inicio rápido

1. git clone https://github.com/alebgl77/ftp-deploy-mcp.git && cd ftp-deploy-mcp

2. Ejecuta install.cmd (doble clic, Windows) o ./install.sh (macOS / Linux).

3. Reinicia tu IDE y pide a tu agente: "Despliega ./dist a producción".

Cómo funciona

flowchart LR
subgraph agents [AI agents]
  A[Claude Code]; B[Cursor]; C[Windsurf]; D[Trae]; E[Antigravity]
end
agents -- MCP stdio --> S[ftp-deploy-mcp<br/>10 tools · path jail · read-only guard]
S -- FTP / FTPS --> F[(your web hosts)]
S -- SFTP --> G[(your servers)]
K[ftp-servers.json<br/>credentials stay local] -.-> S

1. Qué es

Un servidor MCP (Model Context Protocol) que se ejecuta sobre stdio y expone 10 herramientas a tu agente de codificación. Las credenciales viven en un archivo de configuración local y nunca viajan a través del contexto del LLM. Cada operación remota está confinada bajo una root que eliges por servidor.

Requiere Node.js >= 18. Sin dependencias nativas que compilar.

2. Instalación

⚡ Instalación con un comando (recomendado)

git clone https://github.com/alebgl77/ftp-deploy-mcp.git
cd ftp-deploy-mcp

Luego inicia el asistente:

• Windows: haz doble clic en install.cmd.

• macOS / Linux: ./install.sh (ejecuta chmod +x install.sh primero si es necesario).

• O manualmente: npm install && npm run setup.

El asistente setup lo hace todo por ti:

• crea o importa tu configuración de servidores (incluida una importación de FileZilla de tus sitios existentes);

• prueba la conexión a cada servidor;

• escribe automáticamente los archivos de configuración de los clientes MCP detectados (Claude Code, Claude Desktop, Cursor, Windsurf, Antigravity), con una copia de seguridad .backup-<fecha> antes de modificar cualquier archivo existente;

• imprime (y copia) un bloque listo para pegar para Trae, que se configura desde su interfaz.

Luego reinicia tu IDE y pide a tu agente, p. ej., "Lista mis servidores FTP".

Diagnóstico y opciones

En cualquier momento, un diagnóstico de solo lectura (no escribe nada):

npm run doctor          # or: node src/index.js doctor

Imprime la versión de Node, qué archivo de configuración está en uso, la lista de servidores (nunca las contraseñas) y, por cliente, si la entrada ftp está conectada a esta instalación.

Opciones de setup (node src/index.js setup [opciones]):

(b) Instalación global

npm install -g .

El comando ftp-deploy-mcp ahora está en tu PATH; úsalo en lugar de node .../src/index.js.

(c) Publicar en npm (para uso con npx -y)

Si publicas este paquete en npm bajo tu propio nombre, los clientes pueden ejecutarlo sin instalación previa:

{ "command": "npx", "args": ["-y", "your-package-name"] }

3. Configuración del servidor

Crea un archivo ftp-servers.json. El servidor lo busca en este orden (el primero que encuentre gana):

1. --config <ruta> (bandera de línea de comandos)

2. variable de entorno FTP_MCP_CONFIG (ruta al JSON)

3. ./ftp-servers.json (directorio de trabajo del proceso)

4. ~/.ftp-mcp/servers.json

Esquema completo

{
  "defaultServer": "prod",          // optional: used when "server" is not given
  "servers": {
    "prod": {
      "protocol": "sftp",           // REQUIRED: "ftp" | "ftps" | "sftp"
      "host": "ssh.example.com",    // REQUIRED
      "port": 22,                    // optional (defaults: ftp/ftps 21, implicit ftps 990, sftp 22)
      "user": "deploy",             // REQUIRED
      "password": "${ENV:PROD_PW}", // optional: password (or an env placeholder)
      "privateKeyPath": "~/.ssh/id_ed25519", // optional (sftp); "~" is expanded
      "passphrase": "…",            // optional: private-key passphrase
      "root": "/var/www/site",      // optional (default "/"): ALL ops are jailed under it
      "readOnly": false,             // optional: blocks upload/deploy/mkdir/rename/delete
      "insecureTLS": false,           // optional (ftps): skip certificate checks — requires "allowInsecure"
      "implicitTLS": false,          // optional (ftps): implicit TLS (port 990, legacy servers)
      "allowInsecure": false         // optional: explicit opt-in REQUIRED for plain "ftp" or "insecureTLS"
    }
  }
}

El bloque anterior usa comentarios // solo con fines didácticos. El archivo real debe ser JSON estricto (sin comentarios). Consulta ftp-servers.example.json.

Sustitución de variables de entorno

Cualquier valor de cadena puede contener ${ENV:VARIABLE_NAME}. Se reemplaza con el valor de la variable de entorno al inicio. Si la variable no está definida, las herramientas devuelven un error claro que nombra la variable que falta.

"password": "${ENV:OVH_FTP_PASSWORD}"

Consejos de seguridad

• Prefiere SFTP. El ftp simple y ftps con insecureTLS: true se rechazan por defecto: en esos transportes, un atacante de red puede capturar o alterar credenciales y archivos. Para usarlos de todos modos, debes establecer explícitamente "allowInsecure": true en ese servidor, y cada registro de inicio y resultado de herramienta llevará una advertencia de seguridad visible.

• Añade ftp-servers.json a tu .gitignore (ya está hecho en este repositorio).

• Restringe los permisos del archivo (chmod 600 ftp-servers.json en Unix).

• Prefiere variables de entorno (${ENV:…}) o una clave SSH en lugar de una contraseña en texto plano.

• Usa readOnly: true para servidores en los que el agente nunca deba escribir.

• Establece root lo más restringida posible: el aislamiento evita cualquier fuga con ../.

4. Importar desde FileZilla

¿Ya tienes tus sitios en FileZilla? Conviértelos:

# Auto-detect the default sitemanager.xml location…
node src/index.js import-filezilla

# …or an explicit file, written to an ftp-servers.json
node src/index.js import-filezilla --file /path/sitemanager.xml --out ./ftp-servers.json

Sin --out, el JSON se imprime en stdout. Las contraseñas codificadas en Base64 se decodifican; los sitios sin contraseña almacenada reciben un marcador de posición ${ENV:<NAME>_PASSWORD} (tú mismo estableces la variable). Ejemplo de salida:

{
  "defaultServer": "my-site",
  "servers": {
    "my-site": {
      "protocol": "ftp",
      "host": "ftp.example.com",
      "user": "deploy",
      "password": "…",
      "root": "/www/html"
    }
  }
}

Aviso: el archivo generado contiene contraseñas en texto plano decodificadas: mantenlo fuera del control de versiones (.gitignore) y restringe sus permisos (chmod 600).

Sitios FTP simples: los servidores importados con "protocol": "ftp" (como el ejemplo anterior) se rechazan al conectar hasta que los cambies a sftp/ftps o establezcas explícitamente "allowInsecure": true en ellos; la importación imprime una advertencia para cada uno. Consulta Seguridad.

5. Configuración manual del cliente (si no usas setup)

npm run setup escribe estos archivos automáticamente (con copias de seguridad). Esta sección solo es útil si prefieres configurarlo todo manualmente.

Reemplaza /absolute/path/to/ftp-deploy-mcp/src/index.js con la ruta real (las barras / también funcionan en Windows). Si publicaste el paquete en npm, cambia "command": "node", "args": ["…/src/index.js"] por "command": "npx", "args": ["-y", "your-package-name"].

Las ubicaciones de archivo a continuación son las ubicaciones predeterminadas en el momento de escribir esto; las interfaces de estos productos evolucionan, así que consulta su documentación si es necesario.

Claude Code

.mcp.json en la raíz del proyecto:

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

O en un comando:

claude mcp add ftp -- node /absolute/path/to/ftp-deploy-mcp/src/index.js

Claude Desktop

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

Cursor

~/.cursor/mcp.json (global) o .cursor/mcp.json (proyecto):

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

Trae

Trae no tiene un archivo de configuración estable: todo se hace desde su interfaz. Panel de chat de IA → Configuración/engranaje → MCP → Añadir → Configurar manualmente y luego pega (este es el bloque que setup imprime y copia al portapapeles):

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

Antigravity

Según la versión, el archivo es uno de:

• ~/.gemini/antigravity/mcp_config.json

• variante: ~/.gemini/config/mcp_config.json

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

También puedes usar el panel MCP del agente (gestión de servidores MCP) → añadir un servidor, con la misma estructura.

6. Las 10 herramientas

Todas las rutas remotas (path, remote_path, …) son relativas a la root del servidor y usan estilo POSIX. El parámetro server siempre es opcional (consulta la resolución a continuación).

Resolución del servidor: parámetro server explícito → defaultServer → el único servidor si solo hay uno → de lo contrario, un error que lista los nombres disponibles.

Exclusiones por defecto de ftp_deploy: **/node_modules/**, **/.git/**, .env, .env.*, *.log, .DS_Store, Thumbs.db, ftp-servers.json, **/.ftp-mcp/** (tus globs de exclude se añaden; include restringe a los archivos que coinciden). Los patrones sin barra coinciden a cualquier profundidad (similar a gitignore): un apps/api/.env anidado también se excluye.

7. Ejemplos de prompts

• "Despliega ./dist en el servidor prod."

• "Lista lo que hay en /www en ovh."

• "Obtén el .htaccess de prod y muéstramelo."

• "Haz una prueba en seco de desplegar ./build en /www para que pueda ver qué se enviaría."

• "Renombra index.old.html a index.html en prod."

8. Seguridad

• Transportes seguros por defecto: FTP plano y FTPS con verificación de certificado deshabilitada (insecureTLS: true) son rechazados a menos que la entrada del servidor establezca explícitamente "allowInsecure": true. Cuando se permite, se muestra una advertencia de seguridad al inicio, en ftp_list_servers, en doctor, y se añade a cada resultado de herramienta para ese servidor.

• Raíz restringida: cada operación se normaliza y luego se verifica que permanezca bajo la root del servidor. Cualquier intento de escape (../…) se rechaza, incluso cuando root es /.

• Solo lectura: readOnly: true bloquea toda escritura (subida, despliegue, mkdir, renombrado, eliminación); las lecturas siguen funcionando.

• Credenciales fuera del LLM: las contraseñas, frases de paso y claves nunca se devuelven en la salida de la herramienta.

• Sin telemetría, ninguna conexión saliente aparte de tus propios servidores.

• Conexiones por llamada: cada herramienta abre una conexión, realiza la operación y la cierra: no hay sesión persistente.

9. Solución de problemas

• Tiempo de espera / no se puede conectar (FTP): normalmente el modo pasivo está bloqueado por un cortafuegos. Asegúrate de que los puertos pasivos de tu servidor sean accesibles.

• Autenticación por clave SFTP: establece privateKeyPath (~ se expande) y, si la clave está cifrada, passphrase. Comprueba los permisos de la clave.

• "CONEXIÓN INSEGURA RECHAZADA": el servidor usa FTP plano, o FTPS con verificación de certificado deshabilitada. Cámbialo a sftp (o ftps con un certificado válido), o — solo si aceptas completamente el riesgo de interceptación — establece "allowInsecure": true en ese servidor.

• FTPS autofirmado: insecureTLS: true acepta un certificado no verificado. Esto desactiva la protección contra el hombre en el medio, por lo que también requiere "allowInsecure": true e imprime una advertencia de seguridad en cada llamada. Prefiere instalar un certificado válido.

• FTPS implícito (puerto 990): establece implicitTLS: true (protocolo ftps) para servidores heredados que cifran desde el primer byte, sin un comando AUTH TLS.

• "no server configured": el archivo no se encontró en ninguna de las 4 ubicaciones. Crea ftp-servers.json o pasa --config <ruta> / FTP_MCP_CONFIG=<ruta>.

• El cliente no ve las herramientas después de setup: reinicia completamente el IDE (cierra todas las ventanas, no solo el proyecto), luego verifica la conexión con npm run doctor.

• El servidor se inicia a pesar de una configuración no válida: esto es intencional (a los clientes MCP no les gustan los servidores que mueren al inicio). El error exacto se imprime en stderr al lanzar y se devuelve en cada llamada de herramienta.

Desarrollo

npm test          # runs the full smoke test (local FTP + SFTP, no external network)
node src/index.js --version
node src/index.js --help

Contribuciones

Las contribuciones son bienvenidas: consulta CONTRIBUTING.md para la configuración de desarrollo, los principios del proyecto y la lista de verificación de PR.

Seguridad

¿Encontraste una vulnerabilidad? Por favor, no abras un issue público: consulta SECURITY.md para saber cómo reportarla de forma privada.

Licencia

MIT — consulta LICENSE.