FTP Access

Proporciona acceso a un servidor FTP para operaciones de archivos.

Documentación

Servidor MCP para acceso FTP

Este servidor del Protocolo de Contexto de Modelo (MCP) proporciona herramientas para interactuar con servidores FTP. Permite a Claude.app listar directorios, descargar y subir archivos, crear directorios y eliminar archivos/directorios en servidores FTP.

Características

Listar contenido del directorio: Ver archivos y carpetas en el servidor FTP
Descargar archivos: Obtener el contenido de archivos del servidor FTP
Subir archivos: Crear archivos nuevos o actualizar los existentes
Crear directorios: Crear nuevas carpetas en el servidor FTP
Eliminar archivos/directorios: Eliminar archivos o directorios

Instalación

Instalación mediante Smithery

Para instalar mcp-server-ftp para Claude Desktop automáticamente mediante Smithery:

npx -y @smithery/cli install alxspikers-team/mcp-server-ftp --client claude

Requisitos previos

Node.js 16 o superior
Claude for Desktop (u otro cliente compatible con MCP)

Instalación mediante npm

El servidor se publica como mcp-server-ftp, por lo que no se necesita clonar ni compilar: refiérelo directamente en tu configuración de Claude Desktop:

{
  "mcpServers": {
    "ftp-server": {
      "command": "npx",
      "args": ["-y", "mcp-server-ftp"],
      "env": {
        "FTP_HOST": "ftp.example.com"
      }
    }
  }
}

Compilación desde el código fuente

Linux/macOS

# Clone the repository
git clone https://github.com/alxspiker/mcp-server-ftp.git
cd mcp-server-ftp

# Install dependencies
npm install

# Build the project
npm run build

Windows

# Clone the repository
git clone https://github.com/alxspiker/mcp-server-ftp.git
cd mcp-server-ftp

# Install dependencies and build
npm install
npm run build

Configuración

Para usar este servidor con Claude for Desktop, agrégalo a tu archivo de configuración:

MacOS/Linux

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

{
  "mcpServers": {
    "ftp-server": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-ftp/build/index.js"],
      "env": {
        "FTP_HOST": "ftp.example.com",
        "FTP_PORT": "21",
        "FTP_USER": "your-username",
        "FTP_PASSWORD": "your-password",
        "FTP_SECURE": "false"
      }
    }
  }
}

Windows

Edita %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "ftp-server": {
      "command": "node",
      "args": ["C:\\path\\to\\mcp-server-ftp\\build\\index.js"],
      "env": {
        "FTP_HOST": "ftp.example.com",
        "FTP_PORT": "21",
        "FTP_USER": "your-username",
        "FTP_PASSWORD": "your-password",
        "FTP_SECURE": "false"
      }
    }
  }
}

Solución de problemas de compilación en Windows

Si encuentras problemas de compilación en Windows:

Asegúrate de que Node.js (18.14 o superior) y npm estén instalados correctamente
Intenta ejecutar el compilador de TypeScript directamente: npx tsc
Si aún tienes problemas, puedes usar los archivos precompilados en el directorio build ejecutando:
```
node path\to\mcp-server-ftp\build\index.js
```

Opciones de configuración

Variable de entorno	Descripción	Valor predeterminado
`FTP_HOST`	Nombre de host o dirección IP del servidor FTP	localhost
`FTP_PORT`	Puerto del servidor FTP	21
`FTP_USER`	Nombre de usuario FTP (admite cifrado)	anonymous
`FTP_PASSWORD`	Contraseña FTP (admite cifrado)	(cadena vacía)
`FTP_SECURE`	Usar FTP seguro (FTPS), se ignora cuando `FTP_PROTOCOL=sftp`	false
`FTP_PROTOCOL`	Protocolo a usar: `ftp` o `sftp`	ftp
`FTP_PRIVATE_KEY_PATH`	Ruta a la clave privada SSH para SFTP (p. ej. `~/.ssh/id_ed25519`), o una referencia secreta de 1Password (p. ej. `op://Private/my-server/private key`)	(detección automática)
`FTP_PASSPHRASE`	Frase de contraseña para la clave privada SSH (admite cifrado)	(cadena vacía)
`FTP_ENCRYPTION_KEY`	Clave AES-256 hexadecimal de 64 caracteres para descifrar credenciales: guárdala en el llavero del sistema operativo, no aquí	(deshabilitado)

Soporte SSH / SFTP

Además de FTP simple y FTPS, el servidor admite SFTP (el Protocolo de Transferencia de Archivos SSH), que se ejecuta sobre una conexión SSH cifrada y no está relacionado con FTPS.

Configura FTP_PROTOCOL=sftp para cambiar el servidor al modo SFTP. El puerto predeterminado cambia a 22.

Autenticación

SFTP admite dos métodos de autenticación, elegidos automáticamente:

Clave privada: si se encuentra una clave (ver más abajo), se usa para la autenticación. FTP_PASSPHRASE se usa para descifrar la clave si está protegida por frase de contraseña.
Contraseña: si no se encuentra ninguna clave, FTP_PASSWORD se usa para la autenticación por contraseña.

Descubrimiento de claves

El servidor busca una clave privada en este orden:

La ruta o referencia de 1Password en FTP_PRIVATE_KEY_PATH (si está configurada)
~/.ssh/id_ed25519
~/.ssh/id_rsa
~/.ssh/id_ecdsa

Lectura de la clave desde 1Password

En lugar de mantener la clave privada en un archivo en disco, puedes almacenarla como un elemento de Clave SSH en 1Password y apuntar FTP_PRIVATE_KEY_PATH a una referencia secreta:

"FTP_PRIVATE_KEY_PATH": "op://Private/my-server/private key"

Requisitos:

La CLI de 1Password (op) debe estar instalada y en PATH.
La CLI debe poder autenticarse, ya sea mediante la integración de la aplicación de escritorio de 1Password (la primera lectura puede activar un aviso biométrico/de autorización) o un token de cuenta de servicio en OP_SERVICE_ACCOUNT_TOKEN.

La clave se obtiene una vez por proceso del servidor y se almacena en caché en memoria, por lo que no se te solicita en cada operación SFTP. Nunca se escribe en disco.

Si tu servidor rechaza el formato de la clave, agrega ?ssh-format=openssh a la referencia para forzar el formato de clave privada OpenSSH:

"FTP_PRIVATE_KEY_PATH": "op://Private/my-server/private key?ssh-format=openssh"

Ejemplo de configuración

{
  "mcpServers": {
    "ftp-server": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-ftp/build/index.js"],
      "env": {
        "FTP_HOST": "sftp.example.com",
        "FTP_PORT": "22",
        "FTP_PROTOCOL": "sftp",
        "FTP_USER": "your-username",
        "FTP_PRIVATE_KEY_PATH": "~/.ssh/id_ed25519",
        "FTP_PASSPHRASE": "your-key-passphrase"
      }
    }
  }
}

FTP_PASSPHRASE y FTP_USER admiten ambos el formato cifrado enc:: consulta Cifrado de credenciales.

Cifrado de credenciales

Almacenar contraseñas en texto plano en tu archivo de configuración de Claude es un riesgo de seguridad. El servidor admite cifrado AES-256-GCM para FTP_USER, FTP_PASSWORD y FTP_PASSPHRASE, de modo que la configuración solo contenga texto cifrado.

La clave de cifrado en sí (FTP_ENCRYPTION_KEY) nunca debe almacenarse en el mismo archivo de configuración que las credenciales cifradas, ya que eso anularía el propósito. Guárdala en el llavero del sistema operativo o en una variable de entorno global (ver más abajo).

1. Generar una clave de cifrado

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Mantén esta clave en secreto: trátala como una contraseña maestra.

2. Almacenar la clave en el llavero del sistema operativo (recomendado)

Después de compilar el proyecto, ejecuta el script de configuración único:

npm run build
npm run store-key -- <your-64-char-hex-key>

Esto escribe la clave en el llavero del sistema operativo (Llavero de macOS, Administrador de credenciales de Windows o Servicio secreto de Linux). El servidor la carga automáticamente al iniciarse: no se requiere FTP_ENCRYPTION_KEY en el archivo de configuración.

Opción B: variable de entorno global

Si prefieres no usar el llavero, exporta la clave desde tu perfil de shell (~/.zshrc, ~/.bash_profile, etc.):

export FTP_ENCRYPTION_KEY=<your-64-char-hex-key>

Esto mantiene la clave fuera del archivo de configuración por servidor y, aun así, la pone a disposición del proceso del servidor.

3. Cifrar un valor de credencial

npm run build
FTP_ENCRYPTION_KEY=<your-64-char-hex-key> npm run encrypt-env -- <plaintext-value>

Si ya almacenaste la clave en el llavero o en tu perfil de shell, la variable se detecta automáticamente:

npm run encrypt-env -- <plaintext-value>

La salida es una cadena cifrada autocontenida en el formato enc:<iv_hex>:<tag_hex>:<ciphertext_hex>.

4. Usar los valores cifrados en tu configuración

Coloca solo las credenciales cifradas en la configuración. No agregues FTP_ENCRYPTION_KEY aquí: el servidor la recupera del llavero o de tu entorno de shell.

{
  "mcpServers": {
    "ftp-server": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-ftp/build/index.js"],
      "env": {
        "FTP_HOST": "ftp.example.com",
        "FTP_PORT": "21",
        "FTP_USER": "enc:aabbcc...:ddeeff...:112233...",
        "FTP_PASSWORD": "enc:aabbcc...:ddeeff...:112233...",
        "FTP_SECURE": "false"
      }
    }
  }
}

Los valores que no comienzan con enc: se tratan como texto plano, por lo que puedes cifrar de forma selectiva.

Uso

Después de configurar y reiniciar Claude for Desktop, puedes usar lenguaje natural para realizar operaciones FTP:

"Lista los archivos en el directorio /public de mi servidor FTP"
"Descarga el archivo /data/report.txt del servidor FTP"
"Sube este texto como un archivo llamado notes.txt al servidor FTP"
"Crea un nuevo directorio llamado 'backups' en el servidor FTP"
"Elimina el archivo obsolete.txt del servidor FTP"
"Elimina el directorio vacío /old-project del servidor FTP"

Herramientas disponibles

Nombre de la herramienta	Descripción
`list-directory`	Lista el contenido de un directorio FTP
`download-file`	Descarga un archivo del servidor FTP (los archivos binarios se devuelven codificados en base64)
`upload-file`	Sube un archivo al servidor FTP (pasa `encoding: "base64"` para contenido binario)
`create-directory`	Crea un nuevo directorio en el servidor FTP
`delete-file`	Elimina un archivo del servidor FTP
`delete-directory`	Elimina un directorio del servidor FTP
`rename-file`	Renombra o mueve un archivo o directorio en el servidor FTP
`edit-file`	Reemplaza una cadena exacta en un archivo de texto sin volver a subir todo el contenido del archivo
`append-file`	Agrega contenido a un archivo (lo crea si no existe)

Consideraciones de seguridad

Usa la función de Cifrado de credenciales para evitar almacenar contraseñas en texto plano en tu archivo de configuración.
Prefiere SFTP (FTP_PROTOCOL=sftp) sobre FTP simple o FTPS cuando sea posible: usa SSH y no requiere gestión de certificados.
Considera usar FTPS (FTP seguro) configurando FTP_SECURE=true si tu servidor lo admite pero SFTP no está disponible.
El servidor crea archivos temporales para cargas y descargas en el directorio temporal de tu sistema.

Licencia

MIT