AI导哈

FTP MCP服务器

开源MCP服务器，用于将AI模型连接到远程FTP/SFTP服务器，实现文件管理和操作。

  • by joelchala
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 joelchala/FTP-MCP-Server-Open

使用说明

FTP MCP服务器打开

用于将AI模型（Claude、ChatGPT、Gemini等）连接到远程FTP/SFTP服务器的开源MCP服务器。使用任何兼容MCP的LLM管理、读取、写入和导航远程服务器上的文件。

作者：乔尔·查拉 版本：2.0.0-打开 许可证：MIT

FTP MCP服务器——版本de pago（在线）

有一个具有优化功能的支付版本，可在：

https://ftpmcpserver.site

La版本在线 FTP MCP服务器 它与这个开源版本共享相同的基本代码，但包括特定的修改，以免干扰系统的输入，并提供更流畅的生产体验。如果您正在寻找一个无需配置自己的服务器即可使用的解决方案，则付费版本是理想的选择。

特性

  • 14 MCP工具 --通过FTP/SFTP列出、读取、写入、搜索、创建、删除和重命名文件和目录
  • 双模式 --Stdio（本地CLI）和HTTP（带管理面板的web平台）
  • OAuth 2.0+PKCE --与Claude.ai、ChatGPT、Gemini和其他MCP客户端安全集成
  • Web管理面板 --仪表板、文件资源管理器、站点管理、OAuth凭据
  • 默认情况下为SQLite --零配置数据库，可选MySQL支持
  • AES-256-GCM加密 --FTP凭据在静止时加密
  • FTP和SFTP --完全支持这两种协议
  • 自动恢复 --使用Prisma紧急恢复在FTP/DB故障时自动重新连接
  • 大文件支持 --读取限制高达500MB，写入操作超时时间延长

兼容性

支持的MCP客户端

客户 运输 注意事项
Claude Desktop stdio 通过配置 claude_desktop_config.json
Claude Code stdio 通过CLI配置 claude mcp add
光标 stdio 编辑器设置中的配置
Windsurf stdio 编辑器设置中的配置
claude.ai HTTP+OAuth PKCE 远程MCP连接器
ChatGPT HTTP+OAuth PKCE 远程MCP连接器（如果可用）
Gemini HTTP+OAuth PKCE 远程MCP连接器（如果可用）
任何MCP客户端 stdio/HTTP 取决于客户端支持

需求

  • Node.js >=18（建议为22.x）
  • npm >= 9
  • 访问FTP或SFTP服务器

HTTP模式（web平台）的附加功能

  • 公共域/URL（用于Claude.ai集成）

快速开始

git clone https://github.com/joelchala/FTP-MCP-Server-Open.git
cd FTP-MCP-Server-Open
npm install
npm run build
cp .env.example .env

配置

标准模式（本地使用）

TRANSPORT=stdio
FTP_PROTOCOL=sftp
FTP_HOST=your-server.com
FTP_PORT=22
FTP_USER=your-user
FTP_PASSWORD=your-password
FTP_BASE_PATH=/public_html

HTTP模式（web平台）

TRANSPORT=http
PORT=3000
BASE_URL=https://your-domain.com
DATABASE_URL="file:./data.db"
JWT_SECRET=your_64_hex_char_key
ENCRYPTION_KEY=your_64_hex_char_key
CORS_ORIGINS=https://your-domain.com,https://claude.ai

生成密钥：

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

初始化数据库：

npx prisma db push

启动服务器：

npm start

环境变量

变量 描述 默认值
TRANSPORT MCP传输： stdio 或 http stdio
PORT HTTP服务器端口 3000
BASE_URL 公共服务器URL http://localhost:3000
DATABASE_URL 数据库连接（SQLite或MySQL） file:./data.db
JWT_SECRET JWT签名密钥（HS256） -
ENCRYPTION_KEY AES-256十六进制密钥（64个字符） -
CORS_ORIGINS 允许的CORS源（逗号分隔） BASE_URL
NODE_ENV 环境： production 或 development development
FTP_PROTOCOL 协议： ftp 或 sftp （标准输入模式） sftp
FTP_HOST 服务器主机名（stdio模式） localhost
FTP_PORT 连接端口（stdio模式） 22
FTP_USER FTP用户名（stdio模式） anonymous
FTP_PASSWORD FTP密码（stdio模式） -
SFTP_PRIVATE_KEY_PATH SSH私钥路径 -
FTP_BASE_PATH 根沙盒目录 /public_html
FTP_MAX_FILE_SIZE 最大读取大小（字节） 524288000 （500MB）
FTP_ALLOWED_EXTENSIONS 可写文件扩展名 参见.env.example
FTP_READ_TIMEOUT 读取超时（ms） 120000 （2分钟）

关于大文件的注意事项: FTP_MAX_FILE_SIZE 控制读取操作的最大文件大小。写操作没有人为的限制——唯一的限制来自FTP/SFTP服务器本身。根据您的需要调整这些值。

数据库选项

SQLite（默认） --零配置：

DATABASE_URL="file:./data.db"

MySQL（高级） --更改 provider 在 prisma/schema.prisma 从 "sqlite" 到 "mysql":

DATABASE_URL=mysql://user:password@localhost:3306/ftp_mcp_server_open

认证

Web身份验证（管理面板）

  • 使用电子邮件和密码注册（bcrypt，成本系数12）
  • 使用Cookie进行基于会话的登录（仅httpOnly、安全、SameSite=Lax、24小时TTL）

OAuth 2.0授权码+PKCE（适用于Claude.ai）

Claude.ai使用标准OAuth 2.0流与PKCE（RFC 7636）连接：

  1. 在web面板上注册(/register)并登录
  2. 转到连接页面(/connect)并生成OAuth凭据
  3. 在Claude.ai中，添加一个自定义MCP连接器，URL为： https://your-domain.com/mcp
  4. Claude.ai重定向到 /authorize 您授权访问的位置
  5. 服务器生成一个授权码，Claude.ai将其交换为JWT

自动发现：Claude.ai通过以下方式发现OAuth端点：

  • /.well-known/oauth-protected-resource （RFC 9728）
  • /.well-known/oauth-authorization-server （RFC 8414）

凭证格式:

  • 客户端ID: ftpmcp_ +24个十六进制字符
  • 客户端密码：48个十六进制字符（用bcrypt散列）
  • 访问令牌：JWT HS256，8小时TTL

使用Claude Desktop（stdio模式）

{
  "mcpServers": {
    "ftp-server": {
      "command": "node",
      "args": ["/absolute/path/to/FTP-MCP-Server-Open/dist/index.js"],
      "env": {
        "FTP_PROTOCOL": "sftp",
        "FTP_HOST": "your-server.com",
        "FTP_PORT": "22",
        "FTP_USER": "user",
        "FTP_PASSWORD": "password",
        "FTP_BASE_PATH": "/public_html"
      }
    }
  }
}

使用克劳德代码（stdio模式）

claude mcp add ftp-server \
  -e FTP_PROTOCOL=sftp \
  -e FTP_HOST=your-server.com \
  -e FTP_PORT=22 \
  -e FTP_USER=user \
  -e FTP_PASSWORD=password \
  -e FTP_BASE_PATH=/public_html \
  -- node /absolute/path/to/FTP-MCP-Server-Open/dist/index.js

使用光标/风帆（stdio模式）

查看编辑器的文档，了解如何通过stdio添加MCP服务器。该配置需要与上述相同的环境变量。

MCP工具（14）

站点管理（仅限HTTP模式）

工具 说明
ftp_list_sites 列出已配置的FTP站点
ftp_select_site 选择FTP站点进行操作

连接

工具 说明
ftp_connect 连接到FTP/SFTP服务器
ftp_disconnect 关闭活动连接
ftp_status 显示连接状态

导航

工具 说明
ftp_list_directory 列出文件和目录
ftp_search_files 按模式递归搜索文件
ftp_get_file_info 获取文件元数据

文件操作

工具 说明
ftp_read_file 读取文本文件内容
ftp_write_file 将内容写入文件
ftp_create_directory 创建新目录
ftp_delete_file 删除文件
ftp_delete_directory 删除目录
ftp_rename 重命名或移动文件/目录

网络面板

HTTP模式包括一个完整的web管理面板：

页面 路线 描述
着陆 / 公共主页
登录 /login 登录
注册 /register 创建帐户
仪表板 /dashboard 带有统计数据的主面板
网站 /sites 管理FTP/SFTP连接
探索者 /explorer 远程文件浏览器和编辑器
项目 /projects 基于项目的视图
连接 /connect 生成OAuth凭据
设置 /settings 个人资料、密码、危险区域
授权 /authorize OAuth授权屏幕（PKCE）

HTTP API终结点

身份验证API

方法 路线 描述
职位 /api/auth/register 注册新用户
职位 /api/auth/login 登录
职位 /api/auth/logout 注销
得到 /api/auth/me 当前用户信息

网站API

方法 路线 描述
得到 /api/sites 列出用户的网站
职位 /api/sites 创建网站
PUT /api/sites/:id 更新网站
删除 /api/sites/:id 删除网站
职位 /api/sites/:id/test 测试FTP/SFTP连接

文件API

方法 路线 描述
得到 /api/files/list 列出目录文件
得到 /api/files/read 读取文件内容
职位 /api/files/write 写入文件内容
得到 /api/files/stat 文件元数据
职位 /api/files/mkdir 创建目录
删除 /api/files/delete 删除文件或目录
职位 /api/files/rename 重命名/移动文件或目录
得到 /api/files/search 按模式搜索文件

OAuth API

方法 路线 描述
得到 /api/oauth/clients 列出OAuth凭据
职位 /api/oauth/clients 生成新凭据
删除 /api/oauth/clients/:id 撤销凭据
职位 /oauth/authorize 生成授权码（PKCE）
职位 /oauth/token JWT的交换代码/凭据

设置API

方法 路线 描述
PUT /api/settings/profile 更新姓名/电子邮件
PUT /api/settings/password 更改密码
删除 /api/settings/sessions 关闭所有会话

MCP与探索

方法 路线 描述
发布/获取/删除 /mcp MCP可流式HTTP端点
得到 /.well-known/oauth-protected-resource RFC 9728资源元数据
得到 /.well-known/oauth-authorization-server RFC 8414授权服务器元数据
得到 /health 基本健康检查
得到 /debug/health 详细的健康检查

项目结构

FTP-MCP-Server-Open/
  prisma/
    schema.prisma              # Models: User, Site, OauthClient, Session, AuthorizationCode
  public/
    index.html                 # Landing page
    login.html                 # Login
    register.html              # Registration
    dashboard.html             # Main dashboard
    sites.html                 # Site management
    explorer.html              # File explorer
    projects.html              # Projects view
    connect.html               # MCP connection
    settings.html              # Settings
    authorize.html             # OAuth authorization (PKCE)
    css/style.css              # Dark theme styles
    js/app.js                  # Frontend JavaScript
  src/
    index.ts                   # Main entry (Express + MCP)
    env-loader.ts              # Environment variable loading
    constants.ts               # Global constants
    types.ts                   # TypeScript interfaces
    auth/
      password.ts              # bcrypt hashing
      oauth-credentials.ts     # Client ID/Secret generation
      session.ts               # Session management
      protected-resource.ts    # RFC 9728/8414 OAuth discovery
    config/
      database.ts              # Prisma client singleton with auto-recovery
      encryption.ts            # AES-256-GCM encrypt/decrypt
    middleware/
      auth.web.ts              # Web auth middleware (sessions)
      auth.mcp.ts              # MCP auth middleware (JWT Bearer)
    routes/
      auth.routes.ts           # Register, login, logout
      sites.routes.ts          # FTP sites CRUD
      oauth.routes.ts          # OAuth: authorize, token, credentials
      files.routes.ts          # File operations
      settings.routes.ts       # User settings
      pages.routes.ts          # HTML page serving
    mcp/
      mcp.http.ts              # MCP Streamable HTTP transport
    schemas/
      connection.schema.ts     # Zod connection schemas
      navigation.schema.ts     # Zod navigation schemas
      fileops.schema.ts        # Zod file operation schemas
      site.schema.ts           # Zod site schemas
    services/
      connection.manager.ts    # Dual-mode connection manager
      ftp.client.ts            # FTP client (basic-ftp)
      sftp.client.ts           # SFTP client (ssh2-sftp-client)
      file.utils.ts            # File utilities
    helpers/
      error.helper.ts          # Error formatting
      format.helper.ts         # Response formatting
    tools/
      connection.tools.ts      # Tools: connect, disconnect, status
      navigation.tools.ts      # Tools: list, search, file_info
      fileops.tools.ts         # Tools: read, write, mkdir, delete, rename
      site.tools.ts            # Tools: list_sites, select_site

数据库

SQLite（默认）或MySQL与Prisma ORM。型号：

  • 用户 --使用电子邮件和哈希密码（bcrypt）的用户
  • 网站 --带有加密密码（AES-256-GCM）的FTP/SFTP站点
  • OauthClient --OAuth凭据（客户端ID、哈希客户端密钥）
  • 会话 --具有随机令牌和24小时过期的Web会话
  • 授权码 --OAuth PKCE流的临时代码（10分钟TTL）

安全

  • 沙盒 --操作仅限于 FTP_BASE_PATH 目录
  • 扩展 --只允许对配置的文件扩展名进行写入
  • 加密 --使用AES-256-GCM加密的FTP密码
  • 认证 --bcrypt（成本12）+JWT HS256
  • OAuth PKCE --带有SHA-256代码挑战的授权码
  • 会话 --随机令牌，24小时过期，自动清理
  • 速率限制 -Auth（需要50次/15分钟）、API（需要300次/15分）、MCP（需要60次/min）
  • 头盔 --具有严格CSP的HTTP安全标头
  • 路径遍历 --通过路径净化阻止
  • Cookie --httpOnly，安全，SameSite=Lax

贡献

欢迎投稿！请打开问题或提交拉取请求。

许可证

麻省理工学院

相关 MCP