MCP Server for FTP Access

用于访问 FTP、FTPS 和 SFTP 的 MCP 服务

此 Model Context Protocol (MCP) 服务为 FTP、FTPS 和 SFTP 服务提供文件管理工具。它支持目录列表、二进制安全的下载/上传、文本编辑、追加内容、重命名/移动、创建目录和删除。

协议支持

• FTP — 传统 FTP，通常使用 21 端口。
• FTPS — 使用 TLS 加密的 FTP。使用 FTP_PROTOCOL=ftp 和 FTP_SECURE=true。
• SFTP — SSH 文件传输协议，通常使用 22 端口。SFTP 与 FTPS 是不同的协议，且已由 SSH 加密，因此 FTP_SECURE 不适用于它。

功能

• 列出文件和目录
• 下载和上传文本或二进制文件
• 按路径流式上传和下载本地文件，因此文件大小不受请求限制（可选启用）
• 编辑远程文件中的指定文本
• 向文件追加内容
• 重命名或移动文件/目录
• 创建和删除目录
• 支持 FTP、FTPS 和 SFTP
• SFTP 密码或 SSH 私钥身份验证
• 可选使用 1Password CLI 解析私钥
• 使用 AES-256-GCM 加密凭据值
• 支持操作系统密钥链存储加密密钥

获取方式

• GitHub releases
• npm（mcp-server-ftp）
• Smithery
• Agensi
• Glama
• MseeP.ai

Cursor 插件目录条目正在等待审核。

安装

前置条件

• Node.js 18.14 或更高版本
• 与 MCP 兼容的客户端，例如 Claude Desktop

通过 npm 安装

此服务以 mcp-server-ftp 的名称发布：

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

通过 Smithery 安装（已弃用）

Smithery 将于 2026 年 10 月 31 日关闭其 MCP 代理和连接管理功能，Smithery CLI 也已弃用。届时此安装方式将停止工作 — 请改为通过 npm 安装。

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

Cursor 插件

此仓库也提供 Cursor 插件：.cursor-plugin/plugin.json 和 mcp.json，后者会以 ftp-server 为名运行 npx -y mcp-server-ftp。下方的每个 FTP_* 设置都是插件变量，可在 Cursor 中安装或配置插件时设置。

从源代码构建

git clone https://github.com/alxspiker/mcp-server-ftp.git
cd mcp-server-ftp
npm install
npm run build

配置

FTP 示例

{
  "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_PROTOCOL": "ftp",
        "FTP_USER": "your-username",
        "FTP_PASSWORD": "your-password"
      }
    }
  }
}

FTPS 示例

FTPS 使用启用了 TLS 的常规 FTP 客户端：

{
  "mcpServers": {
    "ftp-server": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-ftp/build/index.js"],
      "env": {
        "FTP_HOST": "ftps.example.com",
        "FTP_PORT": "21",
        "FTP_PROTOCOL": "ftp",
        "FTP_SECURE": "true",
        "FTP_USER": "your-username",
        "FTP_PASSWORD": "your-password"
      }
    }
  }
}

FTP_SECURE 仅在 FTP_PROTOCOL=ftp 时有效。SFTP 已通过 SSH 加密，因此 SFTP 连接路径会忽略此设置。

对于使用自签名证书的可信 FTPS 服务，可在 FTPS 的 env 对象中添加 "FTP_TLS_REJECT_UNAUTHORIZED": "false"。这会保留 TLS 加密，但会停用证书和主机名验证，因此仅在你能独立信任该服务和网络时使用。默认情况下会启用验证。此设置要求 FTP_SECURE=true 和 FTP_PROTOCOL=ftp。

SFTP 示例

{
  "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_HOST	全部	服务器主机名或 IP 地址	localhost
FTP_PORT	全部	服务器端口	FTP/FTPS 为 21，SFTP 为 22
FTP_PROTOCOL	全部	ftp 或 sftp	ftp
FTP_USER	全部	用户名；支持加密的 enc: 值	anonymous
FTP_PASSWORD	全部	密码；支持加密的 enc: 值	空
FTP_SECURE	仅 FTP/FTPS	为 FTP 客户端启用 TLS/FTPS	false
FTP_TLS_REJECT_UNAUTHORIZED	仅 FTPS	验证 FTPS 证书和主机名；设为 false 可允许受信任的自签名证书，但会禁用身份检查	true
FTP_PRIVATE_KEY_PATH	仅 SFTP	SSH 私钥路径或 op:// 1Password 密钥引用	自动检测
FTP_PASSPHRASE	仅 SFTP	SSH 私钥密码短语；支持加密的 enc: 值	空
FTP_ENCRYPTION_KEY	加密凭据	64 个字符的十六进制 AES-256 密钥。本地安装时，建议使用操作系统密钥链或全局环境变量。	已禁用
FTP_LOCAL_ROOTS	本地文件工具	upload-local-file 可读取、download-to-local 可写入的本地目录，以 :（macOS/Linux）或 ;（Windows）分隔。~ 会展开。	已禁用

SFTP 身份验证

SFTP 支持私钥和密码身份验证。

服务器会按以下顺序查找私钥：

1. 如果已设置，则使用 FTP_PRIVATE_KEY_PATH
2. ~/.ssh/id_ed25519
3. ~/.ssh/id_rsa
4. ~/.ssh/id_ecdsa

如果未找到密钥，则使用 FTP_PASSWORD。

从 1Password 读取 SFTP 密钥

FTP_PRIVATE_KEY_PATH 可以包含 1Password 密钥引用，而不是文件系统路径：

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

要求：

• 必须安装 1Password CLI（op），并且可通过 PATH 访问。
• CLI 必须已完成身份验证，可通过桌面应用集成或 OP_SERVICE_ACCOUNT_TOKEN 进行身份验证。

密钥会按需解析并缓存在进程内存中，不会写入磁盘。

如果 SSH 服务器拒绝 1Password 默认导出的密钥格式，请请求 OpenSSH 格式：

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

凭据加密

FTP_USER、FTP_PASSWORD 和 FTP_PASSPHRASE 可以使用 enc: 格式存储为 AES-256-GCM 加密值。

生成加密密钥

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

将密钥存储在操作系统密钥链中（本地安装推荐）

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

如果可用，服务器会从 macOS Keychain、Windows Credential Manager 或 Linux Secret Service 加载密钥。

也可以在进程环境中全局设置密钥：

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

除非部署环境没有单独的密钥存储机制，否则不要将 FTP_ENCRYPTION_KEY 与加密凭据一起放在同一个本地 MCP 配置中。

加密一个值

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

如果操作系统密钥链或 shell 环境中已提供密钥：

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

可用工具

工具	说明
list-directory	列出远程目录的内容
download-file	下载文件；二进制内容以 base64 返回
upload-file	上传文本或 base64 编码的二进制内容
create-directory	创建目录
delete-file	删除文件
delete-directory	删除目录
rename-file	重命名或移动文件或目录
edit-file	替换远程文本文件中的指定文本
append-file	向文件追加内容；如有需要则创建文件
upload-local-file	按路径上传本地文件，采用流式传输；之后检查远程文件大小（需要 FTP_LOCAL_ROOTS）
download-to-local	将远程文件下载到本地路径，采用流式传输，不返回文件内容（需要 FTP_LOCAL_ROOTS）

工具调用会返回机器可读的 structuredContent，且全部 11 个工具都声明了输出架构。版本 1.2.2 引入了兼容性垫片，确保声明的架构采用当前 MCP 客户端要求的 JSON Schema 2020-12 方言。

传输本地文件

upload-file 和 download-file 会通过工具调用本身传递文件内容，因此适用于较小的文本文件。对于较大的文件，例如构建好的单页应用或图像，Agent 就必须将整个文件写入请求中，而大多数客户端都无法做到这一点。upload-local-file 和 download-to-local 则接受运行此服务的计算机上的路径，并直接流式传输文件，因此文件大小仅受连接限制。

必须先列出可使用的文件夹，这些工具才会启用：

"env": {
  "FTP_HOST": "ftp.example.com",
  "FTP_USER": "your-username",
  "FTP_PASSWORD": "your-password",
  "FTP_LOCAL_ROOTS": "~/Sites/build:~/Downloads/uploads"
}

• 如果路径不在允许的文件夹内，系统会在查询其任何信息之前拒绝该路径，因此无论该路径或其父文件夹是否存在，回复都相同。
• 系统会在跟随符号链接后解析路径，因此，允许文件夹内指向外部位置的链接会被拒绝。上传会在检查完成后打开单个文件描述符（平台支持时使用 O_NOFOLLOW），并通过该描述符读取文件，因此文件无法在检查和传输之间被替换。
• download-to-local 会将文件写入目标位置旁边的临时文件。该文件使用随机名称并以独占方式创建（O_CREAT | O_EXCL，并在可用时使用 O_NOFOLLOW），且只通过其文件描述符写入，因此即使有人在该名称处放置文件或符号链接，也无法重定向下载。
• 当 overwrite 为 false（默认值）时，下载完成后会通过不替换目标的操作提交文件（硬链接，或在文件系统不支持硬链接时进行独占复制），因此下载期间出现在目标位置的文件绝不会被替换。当 overwrite: true 时，文件会被重命名并覆盖目标。若目标位置已有符号链接，系统会拒绝操作；成功或失败后都会移除临时文件。
• upload-local-file 会报告文件大小和 SHA-256，并将服务器随后报告的文件大小（FTP SIZE 或 SFTP stat）与本地文件大小进行比较。

可选的 HOL Guard 保护

HOL Guard 提供可选择启用的 FTP MCP 配置（mcp.ftp，目录 ID 为 command.mcp-ftp），已在 PR #4514 中合并。请使用包含此贡献的 HOL Guard 发行版或源码构建版本；合并前发布的版本不包含此功能。

使用此配置：

1. 安装 HOL Guard，并按照其设置说明为 MCP 客户端配置保护。
2. 按照npm 配置所示，通过 npx mcp-server-ftp 启动此服务。
3. 通过 HOL Guard 的保护中心在本地启用 FTP MCP。

启用后，递归删除远程目录及其内容之前，delete-directory 需要经过人工审核。其他工具和未知工具沿用现有的 Guard 策略。设备上的自定义授权优先于新增的默认设置，且更严格的保护要求仍然有效。

此配置默认关闭。它适用于通过 npx 启动的 npm 包；直接运行 node build/index.js 不在此配置的适用范围内。

安全说明

• 如果可以，请优先使用 SFTP；它使用 SSH 加密和密钥认证，无需配置 FTPS 证书。
• 仅当使用 FTP 协议路径连接 FTPS 服务时，才使用 FTP_SECURE=true。
• 如果客户端配置中原本会包含明文凭据，请使用凭据加密。
• 除非设置了 FTP_LOCAL_ROOTS，否则本地文件传输默认关闭。请将列表限制为允许 Agent 从中上传或下载到其中的文件夹；这些文件夹中的任何内容都可以上传到服务器。
• FTP 和 SFTP 传输可能会在上传、下载或追加操作期间使用短期本地临时文件；每次操作后清理时都会移除这些文件。

Windows 构建故障排除

1. 确认已安装 Node.js 18.14 或更高版本以及 npm。
2. 运行 npm install。
3. 运行 npm run build 或 npx tsc。
4. 使用 node build/index.js 启动编译后的服务。

许可证

MIT