FTP Access

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

Documentação

Servidor MCP para Acesso FTP

Este servidor Model Context Protocol (MCP) fornece ferramentas para interagir com servidores FTP. Ele permite que o Claude.app liste diretórios, baixe e envie arquivos, crie diretórios e exclua arquivos/diretórios em servidores FTP.

Recursos

Listar Conteúdo do Diretório: Visualize arquivos e pastas no servidor FTP
Baixar Arquivos: Recupere o conteúdo de arquivos do servidor FTP
Enviar Arquivos: Crie novos arquivos ou atualize os existentes
Criar Diretórios: Crie novas pastas no servidor FTP
Excluir Arquivos/Diretórios: Remova arquivos ou diretórios

Instalação

Instalando via Smithery

Para instalar o mcp-server-ftp para Claude Desktop automaticamente via Smithery:

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

Pré-requisitos

Node.js 16 ou superior
Claude para Desktop (ou outro cliente compatível com MCP)

Instalando via npm

O servidor é publicado como mcp-server-ftp, portanto não é necessário clonar ou compilar — basta referenciá-lo diretamente na configuração do Claude Desktop:

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

Compilando a partir do código-fonte

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

Configuração

Para usar este servidor com o Claude para Desktop, adicione-o ao seu arquivo de configuração:

MacOS/Linux

Edite ~/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

Edite %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"
      }
    }
  }
}

Solução de Problemas de Compilação no Windows

Se você encontrar problemas de compilação no Windows:

Certifique-se de que o Node.js (18.14 ou mais recente) e o npm estejam instalados corretamente
Tente executar o compilador TypeScript diretamente: npx tsc
Se ainda houver problemas, você pode usar os arquivos pré-compilados no diretório build executando:
```
node path\to\mcp-server-ftp\build\index.js
```

Opções de Configuração

Variável de Ambiente	Descrição	Padrão
`FTP_HOST`	Hostname ou endereço IP do servidor FTP	localhost
`FTP_PORT`	Porta do servidor FTP	21
`FTP_USER`	Nome de usuário FTP (suporta criptografia)	anonymous
`FTP_PASSWORD`	Senha FTP (suporta criptografia)	(string vazia)
`FTP_SECURE`	Usar FTP seguro (FTPS), ignorado quando `FTP_PROTOCOL=sftp`	false
`FTP_PROTOCOL`	Protocolo a usar: `ftp` ou `sftp`	ftp
`FTP_PRIVATE_KEY_PATH`	Caminho para a chave privada SSH para SFTP (ex.: `~/.ssh/id_ed25519`), ou uma referência secreta do 1Password (ex.: `op://Private/my-server/private key`)	(detecção automática)
`FTP_PASSPHRASE`	Frase secreta para a chave privada SSH (suporta criptografia)	(string vazia)
`FTP_ENCRYPTION_KEY`	Chave AES-256 hexadecimal de 64 caracteres para descriptografar credenciais — armazene no chaveiro do sistema operacional, não aqui	(desativado)

Suporte a SSH / SFTP

Além de FTP simples e FTPS, o servidor suporta SFTP — o SSH File Transfer Protocol — que opera sobre uma conexão SSH criptografada e não está relacionado ao FTPS.

Defina FTP_PROTOCOL=sftp para alternar o servidor para o modo SFTP. A porta padrão muda para 22.

Autenticação

O SFTP suporta dois métodos de autenticação, escolhidos automaticamente:

Chave privada — se uma chave for encontrada (veja abaixo), ela é usada para autenticação. FTP_PASSPHRASE é usado para descriptografar a chave se ela estiver protegida por frase secreta.
Senha — se nenhuma chave for encontrada, FTP_PASSWORD é usado para autenticação por senha.

Descoberta de chave

O servidor procura por uma chave privada nesta ordem:

O caminho ou referência do 1Password em FTP_PRIVATE_KEY_PATH (se definido)
~/.ssh/id_ed25519
~/.ssh/id_rsa
~/.ssh/id_ecdsa

Lendo a chave do 1Password

Em vez de manter a chave privada em um arquivo no disco, você pode armazená-la como um item de Chave SSH no 1Password e apontar FTP_PRIVATE_KEY_PATH para uma referência secreta:

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

Requisitos:

O CLI do 1Password (op) deve estar instalado e no PATH.
O CLI deve ser capaz de autenticar — seja pela integração com o aplicativo de desktop do 1Password (a primeira leitura pode acionar um prompt biométrico/de autorização) ou por um token de conta de serviço em OP_SERVICE_ACCOUNT_TOKEN.

A chave é buscada uma vez por processo do servidor e armazenada em cache na memória, para que você não seja solicitado a cada operação SFTP. Ela nunca é gravada no disco.

Se o seu servidor rejeitar o formato da chave, acrescente ?ssh-format=openssh à referência para forçar o formato de chave privada OpenSSH:

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

Exemplo de configuração

{
  "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 e FTP_USER ambos suportam o formato criptografado enc: — veja Criptografia de Credenciais.

Criptografia de Credenciais

Armazenar senhas em texto simples no arquivo de configuração do Claude é um risco de segurança. O servidor suporta criptografia AES-256-GCM para FTP_USER, FTP_PASSWORD e FTP_PASSPHRASE para que a configuração contenha apenas texto cifrado.

A própria chave de criptografia (FTP_ENCRYPTION_KEY) nunca deve ser armazenada no mesmo arquivo de configuração que as credenciais criptografadas — isso anularia o propósito. Armazene-a no chaveiro do sistema operacional ou em uma variável de ambiente global (veja abaixo).

1. Gere uma chave de criptografia

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

Mantenha esta chave em segredo — trate-a como uma senha mestra.

2. Armazene a chave no chaveiro do sistema operacional (recomendado)

Após compilar o projeto, execute o script de configuração única:

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

Isso grava a chave no chaveiro do sistema operacional (Keychain do macOS, Gerenciador de Credenciais do Windows ou Secret Service do Linux). O servidor a carrega automaticamente na inicialização — sem necessidade de FTP_ENCRYPTION_KEY no arquivo de configuração.

Opção B: variável de ambiente global

Se preferir não usar o chaveiro, exporte a chave do seu perfil de shell (~/.zshrc, ~/.bash_profile, etc.):

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

Isso mantém a chave fora do arquivo de configuração por servidor, enquanto ainda a disponibiliza para o processo do servidor.

3. Criptografe um valor de credencial

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

Se você já armazenou a chave no chaveiro ou no perfil do shell, a variável é detectada automaticamente:

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

A saída é uma string criptografada autocontida no formato enc:<iv_hex>:<tag_hex>:<ciphertext_hex>.

4. Use os valores criptografados na sua configuração

Coloque apenas as credenciais criptografadas na configuração. Não adicione FTP_ENCRYPTION_KEY aqui — o servidor a recupera do chaveiro ou do ambiente do 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"
      }
    }
  }
}

Valores que não começam com enc: são tratados como texto simples, para que você possa criptografar seletivamente.

Uso

Após configurar e reiniciar o Claude para Desktop, você pode usar linguagem natural para realizar operações FTP:

"Liste os arquivos no diretório /public do meu servidor FTP"
"Baixe o arquivo /data/report.txt do servidor FTP"
"Envie este texto como um arquivo chamado notes.txt para o servidor FTP"
"Crie um novo diretório chamado 'backups' no servidor FTP"
"Exclua o arquivo obsolete.txt do servidor FTP"
"Remova o diretório vazio /old-project do servidor FTP"

Ferramentas Disponíveis

Nome da Ferramenta	Descrição
`list-directory`	Lista o conteúdo de um diretório FTP
`download-file`	Baixa um arquivo do servidor FTP (arquivos binários são retornados codificados em base64)
`upload-file`	Envia um arquivo para o servidor FTP (passe `encoding: "base64"` para conteúdo binário)
`create-directory`	Cria um novo diretório no servidor FTP
`delete-file`	Exclui um arquivo do servidor FTP
`delete-directory`	Exclui um diretório do servidor FTP
`rename-file`	Renomeia ou move um arquivo ou diretório no servidor FTP
`edit-file`	Substitui uma string exata em um arquivo de texto sem reenviar todo o conteúdo do arquivo
`append-file`	Acrescenta conteúdo a um arquivo (cria-o se não existir)

Considerações de Segurança

Use o recurso de Criptografia de Credenciais para evitar armazenar senhas em texto simples no arquivo de configuração.
Prefira SFTP (FTP_PROTOCOL=sftp) em vez de FTP simples ou FTPS quando possível — ele usa SSH e não requer gerenciamento de certificados.
Considere usar FTPS (FTP seguro) definindo FTP_SECURE=true se o seu servidor suportar, mas o SFTP não estiver disponível.
O servidor cria arquivos temporários para uploads e downloads no diretório temporário do seu sistema.

Licença

MIT