ftp-ssh-mcp

ftp-ssh-mcp

一个用于通过 FTP、FTPS、SFTP 和 SSH 操作单台远程主机的 MCP 服务——这类主机通常由普通的共享主机方案或纯 VPS 提供，而不是云服务商的 API。它将工具分为三类能力：文件传输（列出、上传、下载、创建目录、删除）、通过 SSH 执行 Shell 命令，以及同样通过 SSH 运行的 MySQL 查询封装器。默认仅启用文件传输；Shell 执行和数据库访问均为可选功能，除非你明确启用，否则会保持关闭。请将这两者视为同样危险：mysql_query 会在生产数据库上运行任意 SQL，还能逃逸到 Shell，因此它并不比另一项更安全。

安装

已发布到 npm，可通过 npx 运行——无需克隆或构建。需要 Node 20 或更高版本。支持 Windows、macOS 和 Linux。

1. 将其添加到 MCP 客户端

在 Windows 上，请使用下方为每个客户端展示的 cmd /c 形式。 大多数客户端会直接启动 command，而不是通过 Shell 启动；Windows 上的 npx 是一个 .cmd 垫片，无法以这种方式执行——服务只会启动失败，通常也不会提供有用的错误信息。在 Windows 上请将此视为通用规则，而非特殊情况。

{
  "mcpServers": {
    "remote": { "command": "npx", "args": ["-y", "ftp-ssh-mcp@1"] }
  }
}

{
  "mcpServers": {
    "remote": { "command": "cmd", "args": ["/c", "npx", "-y", "ftp-ssh-mcp@1"] }
  }
}

{
  "servers": {
    "remote": { "command": "npx", "args": ["-y", "ftp-ssh-mcp@1"] }
  }
}

[mcp_servers.remote]
command = "npx"
args = ["-y", "ftp-ssh-mcp@1"]

[mcp_servers.remote]
command = "cmd"
args = ["/c", "npx", "-y", "ftp-ssh-mcp@1"]

2. 指向一台主机

在项目根目录中创建 .env 文件。服务会从工作目录读取该文件；对于项目范围的客户端，工作目录就是项目根目录：

REMOTE_HOST=ftp.example.com
REMOTE_USER=deploy
REMOTE_PASSWORD=your-password
REMOTE_BASE_DIR=/home/deploy/public_html

这样就足以通过 FTPS 使用六种文件工具。请勿将此文件纳入版本控制——将 .env 和 .env.* 添加到 .gitignore。服务读取 .env，正是为了避免将凭据放入受版本控制的配置文件中。

如果你的客户端没有项目目录（例如 Claude Desktop），或者你想针对不同账户运行多个服务，请为每个服务指定各自的文件：

{
  "mcpServers": {
    "prod": {
      "command": "npx",
      "args": ["-y", "ftp-ssh-mcp@1"],
      "env": { "MCP_ENV_FILE": "/absolute/path/to/.env.prod" }
    }
  }
}

以下是更完整的配置，增加了 Shell 执行和数据库访问——除非选择启用，否则这两项都会保持关闭：

REMOTE_HOST=example.com
REMOTE_USER=deploy
REMOTE_PASSWORD=your-password
REMOTE_BASE_DIR=/home/deploy/public_html

# Pin the host key. Without this, any host key is accepted — see Security.
SSH_HOST_FINGERPRINT=SHA256:your-fingerprint-here
SSH_PORT=22
SSH_BASE_DIR=/home/deploy
SSH_ALLOW_EXEC=true
SSH_ALLOWED_CMDS=@basic,@node

# Runs the mysql client on the host over SSH. At least as dangerous as
# SSH_ALLOW_EXEC — read the Security section before enabling.
DB_USER=deploy_dbuser
DB_PASSWORD=your-db-password
DB_NAME=deploy_db

# Off by default; required for file_delete.
REMOTE_ALLOW_DELETE=true

所有变量请参见 .env.example；每个变量的作用请参见下方的“配置”。

3. 在依赖它之前先进行检查

npx -y ftp-ssh-mcp@1 --selftest

在存放 .env 的目录中运行它。它会解析配置、注册工具并打印一行摘要——但不会打开连接——然后退出。在将服务接入客户端之前，可用它确认已启用正确的功能：

ftp-ssh-mcp 1.0.1 selftest OK. env=.env, transport=ftp, host=example.com,
capabilities=[files, ssh, mysql], tools=[file_list, file_upload, ...]

如果配置不完整，它会以非零状态码退出，并提示缺少哪个变量。请参阅故障排除。

选项

在读取任何配置之前，--version 和 --help 就会作出响应，因此即使机器尚未进行任何设置，也能使用这两个选项。它们都会将内容打印到 stdout；服务的其他所有输出都会发送到 stderr，因为 stdout 是 JSON-RPC 通道。

--quiet 会隐藏关于缺少 DB_PASSWORD、未注册任何工具的 MCP_CAPABILITIES 项以及相对基目录的警告。它有意不会隐藏另外两条警告：它们指出你的安全状况可能不如你想象的可靠——主机密钥未经验证，或路径限制已关闭。客户端配置文件中设置一次标志后，便不会再检查该标志，因此在你修复问题之前，这些警告会一直显示。这才是值得保留的提醒。

功能

只有在功能已配置（设置了所需变量），并且（如果 MCP_CAPABILITIES 限制了功能集合）该功能也列在其中时，才会注册它对应的工具。

files 工具与传输方式无关：它们会使用 FILE_TRANSPORT 选择的传输方式（ftp 或 sftp），如果两种配置都已设置，每次调用还可以单独覆盖传输方式。mysql_query 是一个便捷封装，不是数据库驱动——它会通过 SSH 将 SQL 传递给主机上已安装的 mysql 客户端（mysql --user=... --database=... --table，SQL 从 stdin 发送），然后解析该 CLI 的表格输出。它不支持连接池，也不支持参数化查询。提供它是因为大多数共享主机不允许从主机外部连接数据库；如果你需要真正的客户端数据库集成，请改用其他方案，而不要使用 mysql_query。启用它时应与 ssh_exec 一样谨慎，不能掉以轻心——请参阅安全性。

配置

每项设置都会按以下顺序从环境变量中解析：先使用特定配置的变量（FTP_* 或 SSH_*），再使用共享的 REMOTE_* 回退值，最后使用内置默认值。FTP 和 SSH 是两个相互独立的配置，你可以单独配置其中一个、同时配置两个，或分别配置（但至少需要配置一个才能启动）。

通常会从进程环境中读取变量，但服务还会在解析配置前，从当前工作目录加载 .env 文件，因此凭据可以存放在 MCP 客户端自己的配置文件之外（该文件通常会被纳入版本控制）。已设置的真实环境变量优先于 .env 文件。使用 MCP_ENV_FILE 指定其他文件——开头的 ~ 会展开为你的主目录，相对路径会根据工作目录解析；如果设置了该变量但文件不可读，启动将失败，而不会静默回退到 .env 并加载与你指定内容不同的凭据。.env 解析器不支持行内注释——KEY=value # note 会将 = 后的所有内容都视为值，包括 # note，因此请将注释放在单独一行。

密钥继承

非密钥设置（HOST、USER、BASE_DIR）可以自由回退到 REMOTE_*。密钥（PASSWORD、PRIVATE_KEY、PASSPHRASE）只有在该配置未设置自己的 *_USER 时，才会回退到 REMOTE_PASSWORD。配置自己的用户意味着声明一个不同的身份，向该身份发送原本用于其他账户的密码会导致反复认证失败——在许多共享主机上，失败次数过多会触发暴力破解防护，并导致主机级别的账户锁定。如果设置了 FTP_USER（或 SSH_USER），也必须显式设置对应的密码。

变量

命令预设

以 @ 开头的 SSH_ALLOWED_CMDS 条目会展开为一个命名组；预设和字面命令名称可以自由混用（SSH_ALLOWED_CMDS=@basic,@php,rsync）。未知预设名称会导致启动失败。预设以技术栈而非托管产品命名，展开如下：

如果 DB_USER 没有可解析的 DB_PASSWORD，不会将其视为错误：远程 mysql 客户端可以通过 ~/.my.cnf 或受信任的本地套接字获取凭据，而不是在连接时提供密码。服务器启动时会向 stderr 输出警告，而不会拒绝运行；如果查询随后因身份验证失败，mysql_query 的错误消息会再次指出 DB_PASSWORD，这样就能从 MCP 客户端中看到原因，而不只是从可能没看到的启动日志中得知。

波浪号基目录

~ 和 ~/<dir> 均可接受，并会针对 files 工具展开为该账户自己的登录目录：通过 SFTP 使用 realpath(".")，通过 FTP 使用 PWD。此查找会在连接时进行，且仅在需要展开 ~ 时进行，因此绝对基目录不会产生额外开销，服务器启动时仍无需联网。

ssh_exec 和 mysql_query 会以不同方式解析相同的设置：原始的 ~ 会传给远程登录 shell，由其在每条命令执行时自行展开 $HOME，因此这条路径完全不会在连接时进行查找。实际上，这两种机制的结果一致，因为它们都以同一个已登录账户为依据——只有展开的时机和方式不同。

每个配置档都会根据各自的登录目录展开自己的值。这是有意为之：许多共享主机上的 FTP 账户都处于 chroot 环境中，因此其 ~ 是 /，而 SSH 看到的则是真实的 /home/<user>——所以通过 REMOTE_BASE_DIR 共享的 ~/public_html 在两边都会指向正确位置。

具名主目录 ~other/site 会在启动时被拒绝——但只有注册了 files 工具时才会如此；排除这些工具的配置（例如 MCP_CAPABILITIES=ssh）可以正常启动，直到 ssh_exec 或 mysql_query 首次尝试在那里执行 cd 时才会失败。只能定位已登录账户的主目录，因此具名主目录会作为字面路径发送给服务器。这种情况下请使用绝对路径。

安全性

• ssh_exec 只会运行 SSH_ALLOWED_CMDS 中列出的程序，并根据命令中第一个以空白字符分隔的词进行检查——不会对参数实施策略限制。

• 在进行这项检查之前，如果命令包含以下十四字符 shell 元字符类别中的任何字符（; & | $ ( ) { } < > \ 以及换行符/回车符），就会直接拒绝该命令，因此每次调用都只能是单条普通命令——不能串联命令、重定向或进行替换。

• 传递给 files 工具以及 SSH_BASE_DIR/FTP_BASE_DIR 的远程路径会被解析并限制在配置文件的指定基础目录内；.. 路径段会被直接拒绝。限制按配置文件分别生效，每次调用的 transport 覆盖项会受其所选配置文件的限制，而非默认配置文件。完全没有基础目录的配置文件不受限制——因为没有目录可供限制。因此，每个配置文件在没有自己的基础目录时，都会回退使用另一种传输方式的基础目录；对于最终仍然没有基础目录的任何传输方式，服务会在启动时向 stderr 发出警告。

• 删除操作（REMOTE_ALLOW_DELETE）和 shell 执行（SSH_ALLOW_EXEC）默认都处于关闭状态，必须显式启用。

• 使用 SSH_HOST_FINGERPRINT 固定 SSH 主机密钥。 除非设置了该变量，否则 SSH 和 SFTP 连接会接受对方提供的任何主机密钥——没有可回退使用的 known_hosts 文件——因此网络路径上的任何一方都可以提供自己的密钥，并获取账户密码。设置该变量后，如果密钥不匹配，连接会中止并报错，同时列出预期指纹和收到的指纹；未设置该变量时，服务会在启动时向 stderr 发出警告。请从你信任的主机获取该值：

  ssh-keyscan -t rsa your-host.example.com | ssh-keygen -lf -
  

  并复制 SHA256:… 字段（也接受纯十六进制摘要）。无法解析的指纹会导致启动错误，而不会静默回退到“不验证”。

• mysql_query 不会根据你的 SQL 构造 shell 字符串——查询会写入 mysql 客户端的 stdin，因此绝不会被插入命令行。

• DB_PASSWORD 绝不会出现在主机的进程列表中。 它会作为命令 stdin 的第一行传递，由远程 shell 读入 MYSQL_PWD 并导出给 mysql 进程——因此它不会出现在任何地方的 argv 中，ps aux 只会显示无害的命令文本。该机密只存在于进程环境中，且仅所有者可读取。由这种传递方式带来一项限制：包含换行符的密码会被拒绝，并明确报错。未设置 DB_PASSWORD 时，不会运行任何密码机制，因此主机端凭据（例如 ~/.my.cnf）会真正接管。

• mysql_query 的权限至少与 ssh_exec 一样强大，而非较弱的授权。 它可以对生产数据库执行任意 SQL，而 mysql 客户端的 \! 命令是一种 shell 逃逸方式，并且会在管道输入时生效——因此无论 SSH_ALLOW_EXEC 和 SSH_ALLOWED_CMDS 如何设置，\! curl … | sh 都会调用 shell。这两项能力使用独立开关，是因为它们是不同的功能，而不是因为其中一项更安全；启用 mysql 时应与启用 ssh 一样谨慎。

这些措施并不会让远程主机成为沙箱。获准运行的命令仍会以所配置账户的全部权限运行；ssh_exec 能执行的操作与该账户直接登录后能执行的操作之间没有隔离。这些防护只限制单次调用的形式——一个程序、不使用 shell 技巧、路径不越出基础目录——并不限制获准程序运行后自身所具备的能力。

发现安全问题？请私下报告——参见 SECURITY.md。

已知安全公告

npm install ftp-ssh-mcp 目前会报告 @hono/node-server 的 两项中危安全公告；该依赖由 @modelcontextprotocol/sdk 间接引入。公告涉及该软件包在 Windows 上的静态文件服务器存在路径遍历问题。此服务通过 stdio 通信传输 JSON-RPC，且从不启动 HTTP 监听器，因此这里无法触及这段代码。npm 提供的唯一“修复”是降级 SDK，而这会造成不兼容变更。CI 运行 npm audit --omit=dev --audit-level=high，目前可以通过，但仍会在出现任何高危或严重问题时导致构建失败。SDK 更新其依赖后，这些安全公告将会消除。

故障排除

请先在存放 .env 的目录中运行 npx -y ftp-ssh-mcp@1 --selftest。此命令会重现服务启动时执行的所有操作，但不会建立连接，因此可以区分配置问题和网络或凭据问题。

开发

git clone https://github.com/Chris221/ftp-ssh-mcp.git
cd ftp-ssh-mcp
npm install
npm test
npm run selftest

npm test 会运行 Vitest 测试套件，其中包括针对进程内 FTP 服务的能力注册和传输测试。npm run selftest 会从环境（以及 .env，如果存在）解析配置、注册工具，并打印一行摘要，其中包括解析出的传输方式和已注册的能力；此过程不会打开连接或启动 stdio 传输。