scopweb/mcp-go-ftp

MCP Go FTP Server 🚀

⚠️ BETA VERSION - This project is currently in beta and intended for testing purposes only. Use at your own risk and responsibility.

A Go-based MCP (Model Context Protocol) server for FTP, SFTP, and FTPS operations. Enables AI assistants like Claude to interact with remote file systems securely and efficiently.

✅ Fully tested project - All tests pass successfully

✨ Features

• MCP 2025-11-25 Compliant: Full compliance with latest Model Context Protocol specification (~95%)
• Universal Client Compatibility: Works with Claude Desktop, Cline, and all MCP clients
• Multiple Protocol Support: Simultaneous SFTP, FTP, and FTPS connections
• Predefined Servers: Configure servers once, connect by name only (v2.2.0+)
• Tool Annotations: Security hints (destructive, read-only, idempotent) for safe AI operations (v2.3.0+)
• Complete File Operations: Connect, list, upload, download, delete files
• Remote Directory Management: Navigate and manage remote file systems
• Real-time Connection Status: Monitor active connections
• Advanced Security: SSH host key verification, path sanitization, environment-based credentials
• Robust Validation: Comprehensive error handling and descriptive messages
• Automated Testing: Complete test suite with built-in FTP test server

🛠️ Installation

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

# Build the MCP server
.\compile.bat

# Build the GUI (optional - for testing)
cd src\cmd\gui
go build -o ..\..\..\ftp-gui.exe .
cd ..\..\..

# Run basic tests
.\tests\run-tests.bat

# Run comprehensive tests
.\tests\run-full-tests.bat

🖥️ GUI Testing Tool

A standalone web-based GUI is included for easy testing:

# Run the GUI
.\ftp-gui.exe

The GUI will automatically open in your browser at http://127.0.0.1:9876 and provides:

• Visual file browser (local and remote)
• Connect to servers (predefined or manual)
• Upload/download files via drag & drop or file selection
• Delete remote files
• Real-time operation logs

Perfect for testing FTP operations before integrating with Claude Desktop!

🤖 GitHub Copilot

This repository includes to help GitHub Copilot better understand and assist with this codebase. The instructions provide context about the MCP protocol, project structure, and development guidelines.

⚙️ Claude Desktop Configuration

Basic Configuration (without predefined servers)

{
  "mcpServers": {
    "ftp-mcp": {
      "command": "C:\\path\\to\\mcp-go-ftp\\ftp-mcp-server.exe",
      "args": []
    }
  }
}

With this configuration, you will need to provide credentials each time you connect.

Configuration with Predefined Servers (Recommended)

This configuration allows you to define your servers once and connect by simply using their name.

Step 1: Create servers.json file

Create a servers.json file (you can copy servers.example.json):

{
  "servers": {
    "production": {
      "host": "ftp.example.com",
      "port": 22,
      "username": "admin",
      "password": "env:FTP_PROD_PASS",
      "basePath": "/var/www/html"
    },
    "development": {
      "host": "dev.example.com",
      "port": 22,
      "username": "developer",
      "password": "env:FTP_DEV_PASS",
      "basePath": "/home/developer/projects"
    },
    "backup": {
      "host": "backup.example.com",
      "port": 21,
      "username": "backup_user",
      "password": "your_direct_password_here"
    }
  }
}

Configuration options:

About basePath:

• If you define "basePath": "/var/www/html", when you request to list /, it will actually list /var/www/html
• Useful for restricting access to a specific folder
• If not defined, access is to the entire server (from /)

Step 2: Configure Claude Desktop

Edit your claude_desktop_config.json file:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ftp-mcp": {
      "command": "C:\\path\\to\\ftp-mcp-server.exe",
      "args": ["--config", "C:\\path\\to\\servers.json"],
      "env": {
        "FTP_PROD_PASS": "your_actual_production_password",
        "FTP_DEV_PASS": "your_actual_development_password"
      }
    }
  }
}

Important about passwords:

• Actual passwords go in the "env" section within claude_desktop_config.json
• The servers.json file only contains the reference "env:VARIABLE_NAME"
• This allows versioning servers.json in git without exposing credentials

Step 3: Using with Claude

Now you can tell Claude:

• "Connect to production"
• "List files in development"
• "Upload this file to backup"

Claude will automatically use the configured credentials.

Configuration diagram

┌─────────────────────────────────────────────────────────────────┐
│                    claude_desktop_config.json                    │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ "command": "ftp-mcp-server.exe"                           │  │
│  │ "args": ["--config", "servers.json"]  ──────────┐         │  │
│  │ "env": {                                        │         │  │
│  │   "FTP_PROD_PASS": "password123" ◄──────────────┼────┐    │  │
│  │ }                                               │    │    │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                                                     │    │
                                                     ▼    │
┌─────────────────────────────────────────────────────────────────┐
│                         servers.json                             │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ "production": {                                           │  │
│  │   "host": "ftp.example.com",                              │  │
│  │   "password": "env:FTP_PROD_PASS"  ───────────────────────┼──┘
│  │ }                                                         │
│  └───────────────────────────────────────────────────────────┘
└─────────────────────────────────────────────────────────────────┘

🧪 Available Tools

🚀 Basic Usage

1. Connect to predefined server (Recommended)

ftp_connect:
- name: "production"

You only need the name if the server is configured in servers.json.

1b. List predefined servers

ftp_servers

1c. Connect to SFTP server with credentials

ftp_connect:
- name: "my-server"
- host: "example.com"
- port: "22"
- username: "user"
- password: "password"

1d. Connect using environment credentials

ftp_connect:
- name: "my-server"
- host: "example.com"
- port: "22"
- username: "user"
- password: "env:FTP_PASSWORD"

1e. Connect to traditional FTP server

ftp_connect:
- name: "my-ftp"
- host: "example.com"
- port: "21"
- username: "user"
- password: "password"

1f. Connect to FTPS server

ftp_connect:
- name: "my-ftps"
- host: "example.com"
- port: "990"
- username: "user"
- password: "password"

2. List files

ftp_list:
- name: "my-server"
- path: "/home/user"

3. Upload file

ftp_upload:
- name: "my-server"
- local_path: "C:\\file.txt"
- remote_path: "/home/user/file.txt"

4. Download file

ftp_download:
- name: "my-server"
- remote_path: "/home/user/file.txt"
- local_path: "C:\\download\\file.txt"

🔒 Supported Protocols

• SFTP (port 22): ✅ Fully implemented

  • SSH encrypted connections
  • Password authentication
  • Secure host key verification
  • All operations available

• FTP (port 21): ✅ Fully implemented

  • Traditional FTP
  • Password authentication
  • All operations available

• FTPS (port 990): ✅ Implemented

  • FTP over SSL/TLS
  • Password authentication
  • All operations available

Default port: 22 (SFTP)

🧪 Testing

The project includes a complete automated test suite:

# Basic tests (without FTP server)
.\tests\run-tests.bat

# Complete tests with included FTP server
.\tests\run-full-tests.bat

# Advanced test suite
.\tests\test-suite.exe

Test Status: ✅ All tests pass successfully

• ✅ MCP initialization
• ✅ Tool list
• ✅ FTP/SFTP/FTPS connections
• ✅ File operations (upload/download)
• ✅ Connection management
• ✅ Security and validations

Estructura del Proyecto

├── src/                       # Código fuente
│   ├── main.go               # Punto de entrada
│   ├── internal/             # Código interno
│   ├── go.mod               # Dependencias Go
│   └── go.sum               # Checksums
├── tests/                    # Tests y archivos de prueba
│   ├── test-files/          # Archivos de prueba
│   ├── run-tests.bat        # Tests básicos
│   ├── run-full-tests.bat   # Tests completos
│   ├── test-suite.exe       # Suite avanzada
│   └── ftp-test-server.py   # Servidor FTP de prueba
├── docs/                     # Documentación adicional
│   ├── MANUAL.md            # Manual detallado
│   └── EXAMPLES.md          # Ejemplos de uso
├── servers.example.json     # Ejemplo de configuración de servidores
├── compile.bat              # Script de compilación
├── README.md                # Este archivo
└── CHANGELOG.md             # Historial de cambios

🔒 Security and Credentials

• Host Key Verification: SFTP automatically verifies host keys to prevent MITM attacks
• Secure Credentials: Support for reading passwords from environment variables using env:VARIABLE_NAME
• Predefined Servers: Configure servers once, passwords stay in Claude Desktop (not in shareable files)
• Path Sanitization: All remote paths are sanitized to prevent path traversal attacks
• Validations: Required inputs are verified before executing operations

Security Best Practices

1. Use environment variables for passwords instead of writing them directly
2. Don't version the servers.json file if it contains direct passwords
3. Use SFTP (port 22) instead of FTP (port 21) when possible - it's encrypted
4. The claude_desktop_config.json file is private and not shared

📊 Project Status

• ✅ SFTP Connections: Implemented and tested
• ✅ FTP Connections: Implemented and tested
• ✅ FTPS Connections: Implemented and tested
• ✅ Complete Operations: Upload, download, list, delete, mkdir
• ✅ Predefined Servers: Configure once, connect by name (v2.2.0)
• ✅ Multiple Management: Implemented
• ✅ Security: Host key verification, sanitization, environment variables
• ✅ Tests: Complete automated suite
• ✅ Documentation: Complete and up to date