FT FTP MCP
FT FTP MCP 是一个通过 stdio 运行的本地 MCP Server,让支持 MCP 的 AI Agent 在受控范围内访问 FTP/SFTP 服务器。工程名、Python 包入口和 MCP 注册名统一使用 ft-ftp-mcp-stdio。
- 当前版本:
0.3.1 - 支持的正式分发环境:Windows 10/11 x64 + Python 3.12.x
- 协议:FTP、SFTP
- 许可:MIT License
它提供服务器发现、目录浏览、文件搜索、上传下载、文本预览、目录批量传输及远程文件维护等 14 个 MCP 工具。服务不监听本地网络端口;每次远端工具调用独立建立并关闭 FTP/SFTP 连接。
核心特性
- 本地 stdio 服务:由 MCP 客户端按需启动,不开放 HTTP/TCP 服务端口。
- FTP 与 SFTP:支持密码认证、SFTP 私钥认证和主机密钥校验。
- 凭据不进入模型上下文:密码或私钥口令存入操作系统凭据管理器,也可由环境变量注入。
- 虚拟路径边界:Agent 只使用以
/开头的虚拟路径;/映射到必填的服务器root,真实 root 不进入工具结果。 - 写操作保护:支持只读模式;覆盖、移动和删除均有明确门控。
- 大文件友好:下载内容落入本机暂存目录,工具仅返回路径、元数据和 SHA-256。
- 上传完整性护栏:上传逐文件执行大小限制,并通过同目录临时对象提交;下载校验已知远端大小并清理失败的部分文件。
- 中文环境兼容:FTP 文件名支持 UTF-8、GBK 和自动回退;文本预览支持 BOM、UTF-8 与 GBK。
- 可诊断、可审计:提供只读
doctor检查和不含凭据、文件内容的本地 JSONL 使用日志。
工具一览
| 工具 | 用途 | 关键保护 |
|---|---|---|
list_servers |
列出已配置的逻辑服务器 | 只读本地配置,不连接远端、不读取凭据或触发 TOFU |
test_connection |
测试连接、认证与账号访问范围 | 不执行文件操作 |
list_dir |
列出指定目录的下一层内容 | 最多返回 500 项 |
search_files |
按名称通配符递归搜索 | 深度最多 5 层,最多返回 50 项 |
get_file_info |
获取文件或目录元信息 | 仅查询 |
download_file |
下载单个文件到本机暂存目录 | 校验大小并返回 SHA-256 |
upload_file |
上传单个本机文件 | 默认拒绝覆盖,覆盖需 overwrite=true |
make_dir |
递归创建目录 | 幂等;只读服务器拒绝 |
read_text_preview |
预览文本或 CSV 的开头部分 | 默认 100 KB,最大 1 MB,按完整行截断 |
download_dir |
递归下载目录 | 跳过链接并逐项报告失败,不设置客户端数量或大小上限 |
upload_dir |
递归上传目录 | 默认不覆盖,跳过软链接 |
rename |
在同一目录中重命名 | 目标存在时拒绝 |
move |
移动文件或目录 | 源与目标均进行路径边界检查 |
delete |
删除文件或空目录 | 必须显式传入 confirm=true |
除无业务输入的 list_servers 外,所有远端操作工具都接受可选的 server 参数;省略时使用 default_server。当前行为、返回结构和已知契约缺口以 当前 Spec 基线 为准;机器可读接口以 正式 MCP 工具 Schema 为准。
工作方式
flowchart LR
U[用户] --> A[支持 MCP 的 AI Agent]
A <-->|JSON-RPC / stdio| M[ft-ftp-mcp-stdio]
M -->|FTP 或 SFTP| S[文件服务器]
M --> C[本地配置与系统凭据管理器]
M --> L[暂存目录与使用日志]
MCP 客户端配置只负责启动本地 Server;FTP/SFTP 主机、账号和边界策略保存在 ~/.ft-ftp-mcp/config.json;密码或私钥口令不写入该配置文件。
快速开始
DeepSeek Harness 用户参阅 FT FTP MCP 安装说明。Codex / WorkBuddy 用户按下文完成独立 MCP 安装与手动配置;详细验证结果见 验证记录。
1. 安装发布包
正式分发包为:
ft-ftp-mcp-stdio-offline-0.3.1-py312-win64.zip
请从项目正式分发渠道获取安装包,并在安装前使用包内 SHA256SUMS.txt 校验文件完整性;版本产物信息见 发布说明。
使用前请安装 64 位 Python 3.12.x。解压离线包后运行:
install.bat
安装脚本无需管理员权限,并会:
- 校验 Python 版本;
- 在
%LOCALAPPDATA%\ft-ftp-mcp\venv创建独立虚拟环境; - 从包内
wheels\离线安装本项目和全部依赖; - 在
%LOCALAPPDATA%\ft-ftp-mcp\templates生成包含本机真实路径的 Codex 与 WorkBuddy 配置模板。
安装过程使用 --no-index,不会访问 PyPI。
2. 配置服务器
运行交互式配置向导:
& "$env:LOCALAPPDATA\ft-ftp-mcp\venv\Scripts\python.exe" -m ft_ftp_mcp_stdio setup
向导支持添加、修改和删除服务器,切换默认服务器,设置日志开关并列出当前配置。新增或修改服务器时会先执行真实连接测试,成功后再原子写入配置和凭据。
3. 注册 MCP Server
安装器生成的最终模板位于:
%LOCALAPPDATA%\ft-ftp-mcp\templates\codex-config.toml
%LOCALAPPDATA%\ft-ftp-mcp\templates\workbuddy-mcp.json
将对应片段合并到客户端配置中,保留客户端原有的其他 MCP Server。
Codex 配置示例(~/.codex/config.toml):
[mcp_servers.ft-ftp-mcp-stdio]
command = "C:/Users/<用户名>/AppData/Local/ft-ftp-mcp/venv/Scripts/python.exe"
args = ["-m", "ft_ftp_mcp_stdio"]
[mcp_servers.ft-ftp-mcp-stdio.env]
FASTMCP_SHOW_SERVER_BANNER = "false"
PYTHONUTF8 = "1"
WorkBuddy 配置示例(~/.workbuddy/mcp.json):
{
"mcpServers": {
"ft-ftp-mcp-stdio": {
"command": "C:/Users/<用户名>/AppData/Local/ft-ftp-mcp/venv/Scripts/python.exe",
"args": ["-m", "ft_ftp_mcp_stdio"],
"env": {
"FASTMCP_SHOW_SERVER_BANNER": "false",
"PYTHONUTF8": "1"
}
}
}
}
WorkBuddy 需要在连接器管理中信任该 Server;此后若 command、args 或 env 发生变化,原信任会失效,需要重新信任。配置完成后完全退出并重新打开客户端。
4. 验证
先运行只读诊断:
& "$env:LOCALAPPDATA\ft-ftp-mcp\venv\Scripts\python.exe" -m ft_ftp_mcp_stdio doctor
随后在 Agent 对话中指定服务器别名,例如:
测试一下 ftp1 的连接。
预期 Agent 调用 test_connection,只返回服务器 alias、协议和只读状态,不暴露地址、账号、真实 root 或凭据来源。
配置文件
默认位置:~/.ft-ftp-mcp/config.json。可通过环境变量 FT_FTP_MCP_CONFIG 指定其他路径。
最小完整示例:
{
"version": 2,
"default_server": "ftp1",
"staging_dir": "~/.ft-ftp-mcp/staging",
"log_usage": true,
"servers": [
{
"alias": "ftp1",
"protocol": "ftp",
"host": "ftp.example.com",
"port": 21,
"username": "your_user",
"root": "/",
"description": "示例只读 FTP 服务器",
"readOnly": true,
"max_file_size_bytes": 2147483648,
"encoding": "auto",
"credential_env": null,
"key_path": null,
"host_key_fingerprint": null
}
]
}
重要配置项:
| 字段 | 说明 |
|---|---|
default_server |
工具未传 server 时使用的服务器别名 |
root |
必填的真实服务器根;Agent 的虚拟 / 映射到此处,为 / 时隔离依赖服务端账号权限或 chroot |
description |
可选的非敏感服务器说明,供 list_servers 和 Agent 选择服务器 |
readOnly |
默认 true;只有显式设为 false 才启用写操作,并在连接前检查 |
encoding |
FTP 文件名编码:auto、utf-8 或 gbk |
max_file_size_bytes |
每个上传文件的大小上限,默认 2 GiB;0 表示不限制,不限制下载 |
credential_env |
可选的凭据环境变量名,适合 CI 或企业密管注入 |
key_path |
SFTP 私钥路径;为空时使用密码认证 |
host_key_fingerprint |
可选的 SFTP 主机 SHA-256 指纹强校验 |
log_usage |
是否记录本地 JSONL 使用日志,默认开启 |
远程路径统一使用以 / 开头的虚拟绝对路径;本机 local_path 必须使用本地绝对路径。完整规则见 配置文件规范。
凭据管理
密码和 SFTP 私钥口令默认存入操作系统凭据管理器,服务名为 ft-ftp-mcp-stdio,条目键为服务器别名。
python -m ft_ftp_mcp_stdio cred add <alias>
python -m ft_ftp_mcp_stdio cred list
python -m ft_ftp_mcp_stdio cred remove <alias>
发布包用户应将上述 python 替换为 %LOCALAPPDATA%\ft-ftp-mcp\venv\Scripts\python.exe 的完整路径。
凭据解析时优先读取系统凭据管理器;未找到且配置了 credential_env 时,再读取对应环境变量。SFTP 设置 key_path 后使用私钥认证,钥匙串或环境变量中的值作为可选的私钥口令。
运维命令
# 交互式维护服务器配置
python -m ft_ftp_mcp_stdio setup
# 检查运行环境、配置、凭据、网络和协议登录
python -m ft_ftp_mcp_stdio doctor
# 只诊断指定服务器
python -m ft_ftp_mcp_stdio doctor --server <alias>
doctor 是只读检查,不修改配置、凭据或 known_hosts。任一检查项为 FAIL 时退出码为 1,全部通过时为 0。更多行为与退出码见 命令行工具手册。
本地文件位置
| 路径 | 内容 |
|---|---|
~/.ft-ftp-mcp/config.json |
FTP/SFTP 服务器配置 |
~/.ft-ftp-mcp/config.json.bak.* |
配置向导生成的历史备份 |
~/.ft-ftp-mcp/known_hosts |
SFTP TOFU 主机指纹记录 |
~/.ft-ftp-mcp/staging/ |
下载文件和目录的本机暂存区 |
~/.ft-ftp-mcp/logs/usage-YYYYMMDD.jsonl |
按日本地使用日志 |
使用日志只记录时间、工具名、服务器别名、路径参数、状态和耗时,不记录凭据或文件内容。暂存目录当前不会自动清理,请自行管理磁盘空间。
从源码开发
要求:Python >=3.12,<3.13、uv。
git clone <repository-url>
cd ft-ftp-mcp-stdio
uv sync
常用命令:
# 启动交互式配置向导
uv run ft-ftp-mcp-stdio setup
# 启动只读诊断
uv run ft-ftp-mcp-stdio doctor
# 启动 MCP stdio Server(通常由 MCP 客户端调用)
uv run ft-ftp-mcp-stdio
# 测试、代码检查和类型检查
uv run pytest
uv run ruff check .
uv run mypy src tests scripts
源码环境接入 MCP 客户端时,将 command 指向项目 .venv 中 Python 的绝对路径,args 使用 ['-m', 'ft_ftp_mcp_stdio']。stdio 模式的 stdout 专用于 JSON-RPC,不应向其中输出调试信息。
测试默认不访问真实 FTP/SFTP 服务。--live 测试仅供明确授权的隔离环境使用:它依赖 v2 配置中的 ftp1、sftp1、sftp-key-nopass-v2、sftp-key-pass-v2,并只在记录过初始状态的 /mcp_* 目录中写入和清理数据。确认环境满足 live 测试代码中的前提后,才可显式运行:
uv run pytest --live
不要在未授权的生产环境中运行 live 测试。
项目结构
ft-ftp-mcp-stdio/
├── src/ft_ftp_mcp_stdio/ # MCP 入口、服务层、配置、凭据与协议驱动
├── tests/ # 单元、Schema、CLI、服务层和可选 live 测试
├── docs/ # 产品、配置、Schema、用户与开发文档
├── templates/ # Codex / WorkBuddy 客户端配置源模板
├── scripts/ # 测试夹具及维护脚本
├── wheels/ # Windows 离线安装依赖
├── install.bat # Windows 离线安装器
├── config.example.json # 配置文件示例
└── pyproject.toml # 包元数据与开发依赖
安全边界
- Agent 的远端权限不会超过所配置 FTP/SFTP 账号本身的权限。
- 远端输入输出使用虚拟路径并受
root边界约束;SFTP 逐段拒绝符号链接,FTP 只能拒绝服务器明确报告的链接。 - 本地上传拒绝符号链接、junction 和 reparse point,但不设置允许根目录白名单;可访问范围取决于宿主沙箱和进程权限。
max_file_size_bytes只限制上传;下载和批量调用不设置客户端文件数量或总字节上限。upload_file和upload_dir默认不覆盖;overwrite=true只有在 driver 能确认安全原子替换时才允许。rename和move永不覆盖已存在的目标。delete仅删除文件或空目录,并要求调用参数confirm=true。该参数是工具调用门控,不是插件自行弹出的人工确认窗口。- SFTP 默认使用 TOFU 记录首次主机指纹;敏感环境建议配置管理员提供的
host_key_fingerprint。 - FTP 本身不加密网络传输;敏感数据应优先使用 SFTP。
已知限制
- 不支持 FTPS、断点续传、异步传输和显式传输超时。
- 不提供 GUI、多用户模式或远程 MCP 服务模式。
- 正式离线安装包当前仅提供 Windows x64 版本。
- 另提供 Windows 交叉构建的 macOS 通用离线包,同时支持 arm64(Apple Silicon)和 x86_64(Intel),自动选择对应依赖。Intel 使用 cryptography 48.0.1 兼容锁;使用方法和验证范围见 macOS 安装手册。
- 暂存目录不会自动清理。
- 目录批量传输是 best-effort、非事务操作;必须检查
status、failed和上传结果的indeterminate,不确定时不得整体重试。 - 上传和下载没有客户端批次总量限制,超大目录、磁盘或远端配额耗尽仍是已知资源风险。
read_text_preview只适用于纯文本,不适用于 Word、Excel、PowerPoint、PDF、图片或压缩包。
文档
README 用于项目概览、快速接入和开发入口;完整契约与操作细节以下列专项文档为准:
- 当前 Spec 基线:已经实现、可验证的运行时行为与已知契约缺口
- Windows 快速安装手册:安装、客户端接入、配置和操作示例
- macOS 通用安装手册:Apple Silicon 和 Intel 安装、客户端接入、Keychain 和连接验证
- 产品能力清单:当前功能、兼容性和边界
- 配置文件规范:字段、校验、凭据与路径规则
- 正式 MCP 工具 Schema:从运行时
tools/list生成的 14 个工具机器契约 - MCP 工具 Schema 草案:历史开发草案,仅供追溯,不作为当前契约
- 配置 JSON Schema:
config.json的机器可读基础约束 - 命令行工具手册:
setup、doctor和cred - 发布说明:版本变更与验证记录
许可
本项目基于 MIT License 开源。版权所有 (c) 2026 Ftrans,完整许可条款见 LICENSE。
No comments yet. Be the first to write one.