ftp-deploy-mcp

面向 AI 编码代理的部署按钮。 Claude Code · Claude Desktop · Cursor · Windsurf · Trae · Antigravity → 你自己的 FTP / FTPS / SFTP 服务器。

法语版 → README.fr.md

你的代理运行部署，你只需提出要求。

为什么

• 每个 Web 项目最终都会以同样的方式结束：“现在把它放到服务器上。”

• AI 代理能写出很棒的代码，但大多数无法安全地部署到传统托管环境——OVH、Ionos、Hostinger、o2switch 这类共享主机仍然依赖 FTP/SFTP，而不是 git push。

• ftp-deploy-mcp 给任何 MCP 客户端提供了一条通向你自己服务器的部署路径，发生在编写代码的同一段对话中。

• 与通用型 SSH 执行 MCP 服务端不同，这个专为文件部署而设计：路径隔离、只读模式、试运行，以及永不进入模型上下文的凭据。

Related MCP server: mcp-remote-ssh

功能

快速开始

1. git clone https://github.com/alebgl77/ftp-deploy-mcp.git && cd ftp-deploy-mcp

2. 运行 install（双击，Windows）或 ./install.sh（macOS / Linux）。

3. 重启 IDE 后对代理说：“把 dist 部署到生产环境。”

工作原理

flowchart LR
subgraph agents [AI agents]
  A[Claude Code]; B[Cursor]; C[Windsurf]; D[Trae]; E[Antigravity]
end
agents -- MCP stdio --> S[ftp-deploy-mcp<br/>10 tools · path jail · read-only guard]
S -- FTP / FTPS --> F[(your web hosts)]
S -- SFTP --> G[(your servers)]
K[ftp-servers.json<br/>credentials stay local] -.-> S

1. 这是什么

一个 MCP（Model Context Protocol）服务器，通过 stdio 运行并提供 10 个工具供你的编码代理调用。凭据只会保存在本地配置文件中，永远不会进入 LLM 上下文。每次远程操作都被限制在每个服务器 root 下。

要求 Node.js >= 18，没有需要编译的原生依赖。

2. 安装

⚡ 一键安装(推荐)

git clone https://github.com/alebgl77/ftp-deploy-mcp.git
cd ftp-deploy-mcp

然后打开向导：

• Windows: 双击 install.cmd

• macOS / Linux: ./install.sh (必要时先执行 chmod +x install.sh)

• 手动: npm install && npm run setup

setup 向导会自动完成：

• 创建 或 导入 你的服务器列表 (包括用 FileZilla 导入 现有站点)

• 测试 到每个服务器的连接

• 配置 已检测到的 MCP 客户端 (Claude Code、Claude Desktop、Cursor、Windsurf、Antigravity) — 在修改任何文件之前都会生成 .backup-<时间戳> 备份

• 并打印 可直接粘贴的配置块 给 Trae, Trae 是在它的界面上配置的

一切就绪后，重启 IDE，然后就可以让你的智能体部署了。

诊断和命令

任何时候，一个 只读 检测 (不写任何东西)：

npm run doctor          # or: node src/index.js doctor

它会输出 Node 版本、使用配置文件的路径、服务器列表 (绝不 是密码)，以及每个客户端是否连接到了这个安装。

setup 选项 ( node src/index.js setup [options] )：

(b) 全局安装

npm install -g .

然后 将 ftp-deploy-mcp 放入你的 PATH，以后可以直接使用命令，而不再使用 node .../src/index.js。

(c) 发布到 npm (用于 npx -y)

如果你把这个包以 你自己的名字 发布到 npm，客户端可以运行 npx -y 而不需要提前安装：

{ "command": "npx", "args": ["-y", "your-package-name"] }

3. 服务器配置

保存配置文件 ftp-servers.json。服务器按此顺序搜索：

1. --config <path> (启动参数)

2. FTP_SERVERS_CONF 环境变量 (JSON 路径)

3. ./ftp-servers.json (可以运行加载的命令行所在目录)

4. ~/.ftp-mcp/servers.json

完整结构 (schema)

{
  "defaultServer": "prod",          // optional: used when "server" is not given
  "servers": {
    "prod": {
      "protocol": "sftp",           // REQUIRED: "ftp" | "ftps" | "sftp"
      "host": "ssh.example.com",    // REQUIRED
      "port": 22,                    // optional (defaults: ftp/ftps 21, implicit ftps 990, sftp 22)
      "user": "deploy",             // REQUIRED
      "password": "${ENV:PROD_PW}", // optional: password (or an env placeholder)
      "privateKeyPath": "~/.ssh/id_ed25519", // optional (sftp); "~" is expanded
      "passphrase": "…",            // optional: private-key passphrase
      "root": "/var/www/site",      // optional (default "/"): ALL ops are jailed under it
      "readOnly": false,             // optional: blocks upload/deploy/mkdir/rename/delete
      "insecureTLS": false,           // optional (ftps): skip certificate checks — requires "allowInsecure"
      "implicitTLS": false,          // optional (ftps): implicit TLS (port 990, legacy servers)
      "allowInsecure": false         // optional: explicit opt-in REQUIRED for plain "ftp" or "insecureTLS"
    }
  }
}

上面的配置用 // 注释只是用于说明。 真正的 文件必须是 严格的 JSON 格式 (不允许注释)。请参考 ftp-servers.example.json 。

环境变量的替换

任何字符串值都可以包含 ${ENV:变量名}。它在启动时会被对应的环境变量替换。如果该变量未设置，工具会返回一个明确错误并指出缺少哪个变量。

例子：

假如你有 FTP_PASSWORD=...

"password": "${ENV:OVH_FTP_PASSWORD}"

安全提示

• 优先使用 SFTP。 普通 ftp 和 ftps + insecureTLS: true 是 默认拒绝 的，因为在这些传输中，网络攻击者可以读取或篡改凭据和文件。若要使用，必须在对应的服务器上显式设置 "allowInsecure": true —— 并且从启动后和每次工具调用都会显示安全警告。

• 把 ftp-servers.json 加入 .gitignore (仓库中已添加)。

• 限制文件的权限 (chmod 600 ftp-servers.json 在 Unix 上)。

• 尽量使用 环境变量 (ENV:...) 或 SSH 加密 而不是明文密码。

• 对任何不允许代理写的数据源，请设置 "readOnly": true。

• 让 root 尽可能窄：能防止任何 ../ 越界。

4. 导入 FileZilla

如果你已有 FileZilla 中的站点，可直接导入：

# Auto-detect the default sitemanager.xml location…
node src/index.js import-filezilla

# …or an explicit file, written to an ftp-servers.json
node src/index.js import-filezilla --file /path/sitemanager.xml --out ./ftp-servers.json

如果不传 --out，那么 JSON 会打印到标准输出。Base64 编码的密码会被解码；没有保存密码的站点会得到 ${ENV:<名称>_PASSWORD} 占位符 (由你设置环境变量) 。输出示例：

{
  "defaultServer": "my-site",
  "servers": {
    "my-site": {
      "protocol": "ftp",
      "host": "ftp.example.com",
      "user": "deploy",
      "password": "…",
      "root": "/www/html"
    }
  }
}

注意：生成的文件会包含解码后的明文密码 ——— 请放在 .gitignore 中排除，以及 chmod 600 限制权限。

明文 FTP 站点：用 "protocol": "ftp" 导入的站点（如上例）连接时会被拒绝，除非你将它们改为 sftp 或 ftps，或显式设置 "allowInsecure": true，否则每个站点都会打印警告。参见 技术说明 。

5. 手动配置客户端 (如果不用 setup)

npm run setup 会自动写入这些文件 (带有备份)。如果你希望手动配置，可以参考这一段。

把 /absolute/path/to/ftp-deploy-mcp/src/index.js 替换成实际路径。如果已经发布到 npm，可以把 args 换成 "npx", "-y", "your-package"，而不是 node。

下面列出的配置文件默认位置仅是当前文档撰写时的位置；请参考各开发工具的官方文档来获得最新路径。

Claude Code

项目根目录的 .mcp.json：

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

或一次性命令：

claude mcp add ftp -- node /absolute/path/to/ftp-deploy-mcp/src/index.js

Claude Desktop

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

在服务添加字段：

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

Cursor

~/.cursor/mcp.json (全局) 或 .cursor/mcp.json (项目)：

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

Trae

Trae 没有便捷的配置文件 —— 全部在 UI 中完成。在 Chat 里的服务器配置，选择 Add → Manual Config，然后粘贴 (就是 setup 命令输出的内容)：

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

Antigravity

根据版本不同，文件可能是：

• ~/.gemini/antigravity/mcp_config.json

• 或者是 ~/.gemini/config/mcp_config.json

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

也可以使用代理的 MCP 面板 (MCP server management) → 添加服务器使用同样的格式。

6. 10 个工具

所有远程路径 (path、remote_path 等) 都是 相对 root 的，并使用 POSIX 格式。server 参数总是可选的 (解析规则见下文)。

服务器解析：显式 server 参数 → defaultServer → 如果只有一个服务器则使用该服务器 → 否则返回错误并列出可用名称。

ftp_deploy 默认排除项：**/node_modules/**、**/.git/**、.env、.env.*、*.log、.DS_Store、Thumbs.db、ftp-servers.json、**/.ftp-mcp/**（你的 exclude glob 模式会被追加；include 将限制为匹配的文件）。不带斜杠的模式可匹配任意深度（类似 gitignore）：嵌套的 apps/api/.env 也会被排除。

7. 示例提示词

• "将 ./dist 部署到 prod 服务器。"

• "列出 ovh 上 /www 中的内容。"

• "从 prod 获取 .htaccess 并展示给我。"

• "对将 ./build 部署到 /www 做一次试运行，这样我就能看到会发送什么。"

• "在 prod 上将 index.old.html 重命名为 index.html。"

8. 安全

• 默认使用安全传输：明文 FTP 以及禁用证书验证的 FTPS（insecureTLS: true）会被拒绝，除非服务器条目显式设置 "allowInsecure": true。允许时，会在启动时、ftp_list_servers 中、doctor 中显示安全警告，并附加到该服务器的每个工具结果中。

• 根目录隔离：每个操作都会先规范化，然后验证其保持在服务器 root 之下。任何逃逸尝试（../…）都会被拒绝，即使 root 是 /。

• 只读：readOnly: true 会阻止所有写操作（上传、部署、mkdir、重命名、删除）；读取仍然可用。

• 凭据不进入 LLM：密码、口令和密钥绝不会出现在工具输出中。

• 无遥测，除连接你自己的服务器外，无任何出站连接。

• 每次调用独立连接：每个工具都会打开连接、执行操作并关闭它——没有持久会话。

9. 故障排查

• 超时 / 无法连接（FTP）：通常是被动模式被防火墙阻止。请确保服务器的被动端口可达。

• SFTP 密钥认证：设置 privateKeyPath（~ 会被展开），如果密钥已加密，还需设置 passphrase。检查密钥的权限。

• "INSECURE CONNECTION REFUSED"：服务器使用明文 FTP，或使用禁用证书验证的 FTPS。请将其切换为 sftp（或使用有效证书的 ftps），或者——只有当你完全接受被拦截的风险时——在该服务器上设置 "allowInsecure": true。

• 自签名 FTPS：insecureTLS: true 接受未经验证的证书。这会禁用中间人保护，因此还需要 "allowInsecure": true，并且每次调用都会打印安全警告。建议安装有效证书。

• 隐式 FTPS（端口 990）：对于从第一个字节就开始加密、不使用 AUTH TLS 命令的旧版服务器，请设置 implicitTLS: true（ftps 协议）。

• "no server configured"：在 4 个位置均未找到该文件。请创建 ftp-servers.json，或传入 --config <path> / FTP_MCP_CONFIG=<path>。

• setup 后客户端看不到工具：完全重启 IDE（关闭所有窗口，而不仅仅是项目），然后用 npm run doctor 验证配置。

• 配置无效时服务器仍会启动：这是有意为之（MCP 客户端不喜欢在启动时就崩溃的服务器）。确切的错误会在启动时打印到 stderr，并在每次工具调用时返回。

开发

npm test          # runs the full smoke test (local FTP + SFTP, no external network)
node src/index.js --version
node src/index.js --help

贡献

欢迎贡献——请参阅 CONTRIBUTING.md 了解开发环境搭建、 项目原则和 PR 清单。

安全

发现漏洞？请不要公开提交 issue——请参阅 SECURITY.md 了解如何私下报告。

许可证

MIT——请参阅 LICENSE。