FTP Access

Fornece acesso a um servidor FTP para operações de arquivos.

Documentação

Servidor MCP para Acesso FTP, FTPS e SFTP

Este servidor Model Context Protocol (MCP) fornece ferramentas de gerenciamento de arquivos para servidores FTP, FTPS e SFTP. Ele suporta listagem de diretórios, downloads/uploads seguros para binários, edições de texto, anexos, renomeações/movimentações, criação de diretórios e exclusão.

Suporte a protocolos

FTP — FTP tradicional, normalmente na porta 21.
FTPS — FTP protegido com TLS. Use FTP_PROTOCOL=ftp e FTP_SECURE=true.
SFTP — SSH File Transfer Protocol, normalmente na porta 22. SFTP é um protocolo diferente de FTPS e já é criptografado por SSH, portanto FTP_SECURE não se aplica a ele.

Recursos

Listar arquivos e diretórios
Baixar e enviar arquivos de texto ou binários
Editar texto exato em arquivos remotos
Anexar conteúdo a arquivos
Renomear ou mover arquivos/diretórios
Criar e excluir diretórios
Suporte a FTP, FTPS e SFTP
Autenticação SFTP por senha ou chave privada SSH
Resolução opcional de chave privada via 1Password CLI
Valores de credenciais criptografados com AES-256-GCM
Suporte ao chaveiro do sistema operacional para a chave de criptografia

Instalação

Instalando via Smithery

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

Pré-requisitos

Node.js 18.14 ou mais recente
Um cliente compatível com MCP, como o Claude Desktop

Instalando via npm

O servidor é publicado como mcp-server-ftp:

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

Compilando a partir do código-fonte

git clone https://github.com/alxspiker/mcp-server-ftp.git
cd mcp-server-ftp
npm install
npm run build

Configuração

Exemplo FTP

{
  "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_PROTOCOL": "ftp",
        "FTP_USER": "your-username",
        "FTP_PASSWORD": "your-password"
      }
    }
  }
}

Exemplo FTPS

FTPS usa o cliente FTP normal com TLS habilitado:

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

FTP_SECURE só é significativo quando FTP_PROTOCOL=ftp. Ele é ignorado pelo caminho SFTP porque o SFTP já é criptografado via SSH.

Para um servidor FTPS confiável com certificado autoassinado, adicione "FTP_TLS_REJECT_UNAUTHORIZED": "false" ao objeto env do FTPS. Isso mantém a criptografia TLS, mas desativa a verificação de certificado e nome de host; use apenas quando você confiar independentemente no servidor e na rede. A verificação permanece habilitada por padrão. Esta configuração requer FTP_SECURE=true e FTP_PROTOCOL=ftp.

Exemplo SFTP

{
  "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"
      }
    }
  }
}

Opções de configuração

Variável de ambiente	Aplica-se a	Descrição	Padrão
`FTP_HOST`	todos	Nome de host ou endereço IP do servidor	`localhost`
`FTP_PORT`	todos	Porta do servidor	`21` para FTP/FTPS, `22` para SFTP
`FTP_PROTOCOL`	todos	`ftp` ou `sftp`	`ftp`
`FTP_USER`	todos	Nome de usuário; suporta valores `enc:` criptografados	`anonymous`
`FTP_PASSWORD`	todos	Senha; suporta valores `enc:` criptografados	vazio
`FTP_SECURE`	apenas FTP/FTPS	Habilita TLS/FTPS para o cliente FTP	`false`
`FTP_TLS_REJECT_UNAUTHORIZED`	apenas FTPS	Verifica o certificado e o nome de host do FTPS; `false` permite um certificado autoassinado confiável, mas desativa verificações de identidade	`true`
`FTP_PRIVATE_KEY_PATH`	apenas SFTP	Caminho da chave privada SSH ou referência de segredo `op://` do 1Password	detecção automática
`FTP_PASSPHRASE`	apenas SFTP	Frase secreta da chave privada SSH; suporta valores `enc:` criptografados	vazio
`FTP_ENCRYPTION_KEY`	credenciais criptografadas	Chave AES-256 em hex de 64 caracteres. Prefira o chaveiro do SO ou uma variável de ambiente global para instalações locais.	desabilitado

Autenticação SFTP

O SFTP suporta autenticação por chave privada e senha.

O servidor procura uma chave privada nesta ordem:

FTP_PRIVATE_KEY_PATH, se definido
~/.ssh/id_ed25519
~/.ssh/id_rsa
~/.ssh/id_ecdsa

Se nenhuma chave for encontrada, FTP_PASSWORD é usado.

Lendo uma chave SFTP do 1Password

FTP_PRIVATE_KEY_PATH pode conter uma referência de segredo do 1Password em vez de um caminho de sistema de arquivos:

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

Requisitos:

O CLI do 1Password (op) deve estar instalado e disponível no PATH.
O CLI já deve ser capaz de autenticar, seja pela integração com o aplicativo de desktop ou OP_SERVICE_ACCOUNT_TOKEN.

A chave é resolvida de forma preguiçosa, armazenada em cache na memória do processo e não é gravada em disco.

Se o servidor SSH rejeitar o formato de chave exportado padrão do 1Password, solicite o formato OpenSSH:

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

Criptografia de credenciais

FTP_USER, FTP_PASSWORD e FTP_PASSPHRASE podem ser armazenados como valores criptografados AES-256-GCM usando o formato enc:.

Gerar uma chave de criptografia

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

Armazenar a chave no chaveiro do SO (recomendado para instalações locais)

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

O servidor carrega a chave do Keychain do macOS, do Gerenciador de Credenciais do Windows ou do Secret Service do Linux quando disponível.

Alternativamente, defina a chave globalmente no ambiente do processo:

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

Não coloque FTP_ENCRYPTION_KEY ao lado das credenciais criptografadas no mesmo arquivo de configuração MCP local, a menos que seu ambiente de implantação não ofereça um mecanismo separado de armazenamento de segredos.

Criptografar um valor

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

Se a chave já estiver disponível no chaveiro do SO ou no ambiente do shell:

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

Ferramentas disponíveis

Ferramenta	Descrição
`list-directory`	Lista o conteúdo de um diretório remoto
`download-file`	Baixa um arquivo; conteúdo binário é retornado como base64
`upload-file`	Envia conteúdo de texto ou binário codificado em base64
`create-directory`	Cria um diretório
`delete-file`	Exclui um arquivo
`delete-directory`	Exclui um diretório
`rename-file`	Renomeia ou move um arquivo ou diretório
`edit-file`	Substitui texto exato em um arquivo de texto remoto
`append-file`	Anexa conteúdo a um arquivo, criando-o se necessário

As chamadas de ferramenta retornam structuredContent legível por máquina, e todas as nove ferramentas anunciam esquemas de saída. A versão 1.2.2 introduziu um shim de compatibilidade que garante que os esquemas anunciados usem o dialeto JSON Schema 2020-12 exigido pelos clientes MCP atuais.

Notas de segurança

Prefira SFTP quando disponível; ele usa criptografia SSH e autenticação por chave sem configuração de certificado FTPS.
Use FTP_SECURE=true apenas para servidores FTPS que usam o caminho do protocolo FTP.
Use criptografia de credenciais quando uma configuração de cliente conteria credenciais em texto puro.
Transferências FTP e SFTP podem usar arquivos temporários locais de curta duração para operações de upload/download/anexo; esses arquivos são removidos durante a limpeza após cada operação.

Solução de problemas em builds Windows

Confirme que Node.js 18.14 ou mais recente e npm estão instalados.
Execute npm install.
Execute npm run build ou npx tsc.
Inicie o servidor compilado com node build/index.js.

Licença

MIT