MCP Go Ftp

MCP Go FTP服务器🚀

⚠️ β版 -该项目目前处于测试阶段，仅用于测试目的。使用风险和责任自负。

用于FTP、SFTP和FTPS操作的基于Go的MCP（模型上下文协议）服务器。使像Claude这样的人工智能助手能够安全有效地与远程文件系统进行交互。

✅ 经过全面测试的项目 -所有测试均成功通过

✨ 特性

• 符合MCP 2025-11-25标准：完全符合最新的模型上下文协议规范（~95%）
• 通用客户端兼容性：适用于Claude Desktop、Cline和所有MCP客户端
• 多协议支持：同时进行SFTP、FTP和FTPS连接
• 预定义服务器：配置服务器一次，仅按名称连接（v2.2.0+）
• 工具注释：安全AI操作的安全提示（破坏性、只读、幂等）（v2.3.0+）
• 完成文件操作：连接、列出、上传、下载、删除文件
• 远程目录管理：导航和管理远程文件系统
• 实时连接状态：监视活动连接
• 高级安全：SSH主机密钥验证、路径净化、基于环境的凭据
• 稳健验证：全面的错误处理和描述性消息
• 自动化测试：完整的测试套件，内置FTP测试服务器

🛠️ 安装

# 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测试工具

包含一个独立的基于web的GUI，便于测试：

# Run the GUI
.\ftp-gui.exe

GUI将在您的浏览器中自动打开 http://127.0.0.1:9876 并提供：

• 可视化文件浏览器（本地和远程）
• 连接到服务器（预定义或手动）
• 通过拖放或文件选择上传/下载文件
• 删除远程文件
• 实时操作日志

非常适合在与Claude Desktop集成之前测试FTP操作！

🤖 GitHub Copilot

此存储库包括 副驾驶说明 帮助GitHub Copilot更好地理解和协助此代码库。这些说明提供了有关MCP协议、项目结构和开发指南的上下文。

⚙️ Claude桌面配置

基本配置（无预定义服务器）

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

使用此配置，每次连接时都需要提供凭据。

______________________________________________________________________

使用预定义服务器进行配置（推荐）

此配置允许您定义一次服务器，并仅使用其名称进行连接。

第一步：创建 servers.json 文件

创建一个 servers.json 文件（你可以复制 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"
    }
  }
}

配置选项：

关于 basePath:

• 如果你定义 "basePath": "/var/www/html"，当您请求列出 /，它实际上会列出 /var/www/html
• 有助于限制对特定文件夹的访问
• 如果未定义，则访问整个服务器（从 /)

步骤2：配置Claude桌面

编辑您的 claude_desktop_config.json 文件：

窗户： %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"
      }
    }
  }
}

关于密码的重要信息：

• 实际密码在 "env" 节内 claude_desktop_config.json
• 这 servers.json 文件仅包含引用 "env:VARIABLE_NAME"
• 这允许版本控制 servers.json 在git中不公开凭据

步骤3：与Claude一起使用

现在你可以告诉克劳德：

• “连接到生产”
• “列出正在开发的文件”
• “上传此文件进行备份”

Claude将自动使用配置的凭据。

配置图

┌─────────────────────────────────────────────────────────────────┐
│                    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"  ───────────────────────┼──┘
│  │ }                                                         │
│  └───────────────────────────────────────────────────────────┘
└─────────────────────────────────────────────────────────────────┘

🧪 可用工具

🚀 基本用法

1.连接到预定义的服务器（推荐）

ftp_connect:
- name: "production"

如果服务器在中配置，则只需要该名称 servers.json.

1b。列出预定义服务器

ftp_servers

1c。使用凭据连接到SFTP服务器

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

1d。使用环境凭据连接

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

1e。连接到传统FTP服务器

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

1f。连接到FTPS服务器

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

2.列出文件

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

3.上传文件

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

4.下载文件

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

🔒 支持的协议

• SFTP（端口22）: ✅ 全面实施

- SSH加密连接 - 密码认证 - 安全主机密钥验证 - 所有可用操作

• FTP（端口21）: ✅ 全面实施

- 传统FTP - 密码认证 - 所有可用操作

• FTPS（端口990）: ✅ 实现

- SSL/TLS上的FTP - 密码认证 - 所有可用操作

默认端口: 22 （SFTP）

🧪 测试

该项目包括一个完整的自动化测试套件：

# 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

测试状态: ✅ 所有测试均成功通过

• ✅ MCP初始化
• ✅ 工具列表
• ✅ FTP/SFTP/FTPS连接
• ✅ 文件操作（上传/下载）
• ✅ 连接管理
• ✅ 安全和验证

项目结构

├── 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

🔒 安全和凭据

• 主机密钥验证：SFTP自动验证主机密钥以防止MITM攻击
• 安全凭据：支持使用从环境变量读取密码 env:VARIABLE_NAME
• 预定义服务器：配置服务器一次，密码保留在Claude Desktop中（不在可共享文件中）
• 路径消毒：所有远程路径都经过清理，以防止路径遍历攻击
• 验证：在执行操作之前，验证所需的输入

安全最佳实践

1. 使用环境变量 用于密码，而不是直接写入密码
2. 不要版本 这 servers.json 如果文件包含直接密码
3. 使用SFTP （端口22）而不是FTP（端口21）（如果可能）-它是加密的
4. 这 claude_desktop_config.json 文件是私有的，不共享

📊 项目状态

• ✅ SFTP连接：已实施和测试
• ✅ FTP连接：已实施和测试
• ✅ FTPS连接：已实施和测试
• ✅ 完成操作：上传、下载、列表、删除、mkdir
• ✅ 预定义服务器：配置一次，按名称连接（v2.2.0）
• ✅ 多重管理：已实施
• ✅ 安全：主机密钥验证、净化、环境变量
• ✅ 测试：完整的自动化套件
• ✅ 文档：完整且最新