SFTP MCP 服务器

这是一个提供 SFTP 操作功能的模型上下文协议（MCP）服务器，包括目录同步、单文件上传、文件读取以及远程命令执行。该服务器使用 STDIO 传输方法进行安全本地通信。

项目结构

• src/main.py：MCP 服务器实现，包括 SFTP 工具、资源和提示
• pyproject.toml：项目元数据和依赖项
• requirements.txt：Python 依赖项

安装与设置

此项目使用 Python。注意：MCP 服务器通常由 MCP 客户端（如 Claude Desktop）直接调用，通常不需要手动激活虚拟环境。

方法 1：使用 pip 安装依赖项（推荐）

pip install -r requirements.txt

方法 2：使用 UV 安装依赖项

如果你已经安装了 uv，也可以使用：

uv sync

环境变量配置

所有配置均通过 MCP 客户端的环境变量设置，无需创建 .env 文件。

运行服务

重要通知： MCP 服务器通常不需要手动操作。它们由 MCP 客户端自动启动和管理。

如果需要手动测试，可以使用以下命令：

uv run python src/main.py

服务器将使用 STDio 传输方法运行，并通过 JSON-RPC 2.0 进行通信。

MCP 客户端配置

要在 MCP 客户端中使用此服务器，请按如下方式配置：

{
  "mcpServers": {
    "sftp-server": {
      "command": "uv",
      "args": ["--directory", "/path/to/your/project", "run", "python", "src/main.py"],
      "env": {
        "TARGET_HOST": "your-sftp-server.com",
        "TARGET_USERNAME": "your-username",
        "TARGET_PASSWORD": "your-password",
        "LOCAL_PATH": "/path/to/local/directory",
        "REMOTE_PATH": "/path/to/remote/directory",
        "IGNORE_PATTERNS": "[\"*.log\", \"node_modules/\", \".git/\"]"
      }
    }
  }
}

重要说明：

• 将 /path/to/your/project 翻译成中文并替换为你项目的绝对路径
• 服务器使用 STDIO 传输，因此不会暴露网络端口
• 环境变量可以在 MCP 客户端配置或在 .env 文件中设置

MCP 工具

sync_directory

同步本地目录到远程 SFTP 服务器。

参数

• local_dir（可选）：本地目录路径（默认使用 LOCL_PATH 环境变量）
• remote_dir（可选）：远程目录路径（默认使用 REMOTE-PATH 环境变量）

返回值： 包含同步结果的字典，包括已上传的文件、创建的目录、忽略的项目及任何错误。

upload_file

将单个文件上传到远程 SFTP 服务器。

参数

• local_file_path：要上传的本地文件路径
• remote_file_path（可选）：远程目标路径（未指定时自动确定）

返回值： 包含上传结果的字典，包括文件大小和路径。

read_remote_file

从远程 SFTP 服务器读取文件内容。

参数

• remote_file_path：要读取的远程文件路径
• encoding（可选）：使用的文本编码（默认：utf-8）

返回值： 包含文件内容、大小和编码信息的字典。

execute_remote_command

通过 SSH 在远程服务器上执行命令。

参数

• command：在远程服务器上执行的命令
• working_directory（可选）：命令的工作目录

返回值： 包含命令输出、退出代码、UWP 和 STDerr 的字典。

list_remote_directory

列出远程目录的内容。

参数

• remote_dir_path：要列出的远程目录路径

返回值： 包含目录内容的字典，包括文件名、大小、权限和类型。

MCP 资源

sftp://config

获取当前 SFTP 服务器配置（不包括敏感数据）。

返回包含主机、端口、用户名、路径、忽略模式和连接状态的 JSON。

MCP 提示

sync_workflow

用于同步文件到远程服务器的工作流程提示。提供常见 SFTP 操作的逐步指导。

file_upload_guide

上传单个文件的指南。解释如何有效使用 uploadFILE 工具。

环境变量

变量	描述	默认值
TARGET_HOST	SFTP 服务器主机名或 IP 地址	必填
TARGET_USERNAME	SFTP 用户名	必填
TARGET_PASSWORD	SFTP 密码	必填
LOCAL_PATH	本地目录路径	必填
REMOTE_PATH	远程目录路径	必填
IGNORE_PATTERNS	忽略的文件模式	[]

特性

• 标准 MCP 协议：完全符合 MCP 规范，使用 JSON-RPC 2.0
• Stdio 传输：无网络暴露的安全本地通信
• 目录同步：支持忽略模式下的完整目录同步
• 单文件上传：自动路径解析的单文件上传
• 远程文件读取：支持读取编码的远程服务器文件内容
• 远程命令执行：通过 SSH 在远程服务器上执行命令
• 目录列表：浏览远程目录内容，包括详细文件信息
• 环境配置：通过环境变量灵活设置
• 安全性认证：使用 STDio 传输，无需 API 密钥
• 错误处理：所有操作的全面错误报告

使用示例

同步整个目录

# 使用配置的 LOCAL_PATH 和 REMOTE_PATH
sync_directory()

# 或指定自定义路径
sync_directory("/custom/local/path", "/custom/remote/path")

上传单个文件

# 基于 LOCAL_PATH/REMOTE_PATH 自动确定远程路径
upload_file("/local/path/file.txt")

# 指定确切的远程目标
upload_file("/local/path/file.txt", "/remote/path/file.txt")

读取远程文件

# 使用默认 UTF-8 编码读取
read_remote_file("/remote/path/file.txt")

# 指定编码
read_remote_file("/remote/path/file.txt", "latin-1")

执行远程命令

# 简单命令
execute_remote_command("ls -la")

# 带工作目录的命令
execute_remote_command("npm install", "/var/www/myapp")

列出远程目录

list_remote_directory("/remote/path")

安全注意事项

• 服务器使用 STDIO 传输，消除了网络安全问题
• SFTP 凭证通过环境变量传递
• 敏感数据不会在日志或响应中暴露
• 所有文件操作都限制在配置的路径内
• 使用 paramiko 进行 SSH 连接，并适当处理主机密钥

故障排除

连接问题

• 验证 TARGET_SOST、TARGET-USERNAME 和 TARGET-PASSWORD 是否正确
• 检查 SFTP 服务器是否可以从你的网络访问
• 确保 TARGET-PORT 正确（默认是 22）

路由问题

• 验证 LOCALIZED PATH 的存在和可读性
• 确保 REMOTE-PATH 在远程服务器上存在
• 检查本地和远程系统上的文件权限

忽略模式

• IGNORE-PATTERNS 必须是有效的 JSON 数组格式
• 模式支持 Unix 风格的通配符（*, ?, []）
• 目录模式应以 / 结尾