SSH Remote MCP

一个零运行时第三方依赖的 stdio MCP Server：通过本机 ssh 操作多台远端服务器。 servers.toml 是唯一服务器清单，改清单后运行 sync_servers.py 同步本地 ~/.ssh/config 别名——之后所有 ssh（包括 MCP 工具）只认别名，不记 IP。

• 传输：MCP stdio + SSH（非交互）
• 运行要求：本机 Python 3.10+、OpenSSH Client、可用的 SSH key/agent

工具

工具	作用
remote_run	远端执行 Bash 命令，返回 exit_code、stdout、stderr、duration_ms、timed_out、truncated
remote_read_file	读取允许路径下的 UTF-8 文件
remote_write_file	写入允许路径下的 UTF-8 文件
remote_list_directory	列出允许路径下的目录
remote_upload_file	用 scp 把本地文件传到服务器，支持二进制和大文件，不经过模型上下文
remote_download_file	用 scp 把服务器文件下载到本地，支持二进制和大文件，不经过模型上下文

cwd 和文件路径会做词法校验，只允许落在配置的允许路径内；但 remote_run 本质是 root shell，命令可访问整台服务器，只在可信客户端和可信会话中启用。

快速开始

1. 拉取代码：git clone <本仓库地址> && cd ssh-remote-mcp

2. 编辑 servers.toml，别名 = "IP"（别名不要含点号）。 不想让服务器信息进公开仓库时，把真实清单写在同目录的 servers.local.toml （已被 .gitignore 忽略）；sync_servers.py 优先读取它。

3. 同步别名到本地 ssh 配置：

   python3 sync_servers.py

   脚本维护 ~/.ssh/config 中 # >>> server-mcp managed 标记之间的托管块： 已有则整体替换，没有则追加到末尾；从清单删行再同步即下线该机器。

4. 验证免密登录：

   ssh -o BatchMode=yes <别名> 'pwd'

接入客户端

MCP 对客户端无关，注册命令是同一个模板、换服务器名即可：

claude mcp add --transport stdio --scope user <别名> \
  -e SERVER_MCP_SSH_HOST=<别名> \
  -e SERVER_MCP_SSH_USER=root \
  -e SERVER_MCP_WORKDIR=<远端默认工作目录> \
  -e SERVER_MCP_ALLOWED_PATHS=<逗号分隔的允许路径> \
  -- python3 /path/to/ssh-remote-mcp/mcp_server.py

WORKDIR 和 ALLOWED_PATHS 按目标机器的实际目录填写。

注册统一走全局（--scope user），每台机器一条同模板命令；本仓库不做任何 项目级注册。

配置项

环境变量	默认值	说明
SERVER_MCP_SSH_HOST	remote-server	SSH 主机（~/.ssh/config 别名）
SERVER_MCP_SSH_USER	root	SSH 用户
SERVER_MCP_SSH_PORT	22	SSH 端口
SERVER_MCP_WORKDIR	/home/dev	默认目录及文件工具允许范围
SERVER_MCP_ALLOWED_PATHS	/home/dev	逗号分隔的远端允许路径
SERVER_MCP_IDENTITY_FILE	未设置	SSH 私钥路径；默认使用 SSH 配置/agent
SERVER_MCP_CONNECT_TIMEOUT	10	SSH 连接超时（秒）
SERVER_MCP_STRICT_HOST_KEY_CHECKING	accept-new	yes、no 或 accept-new
SERVER_MCP_MAX_OUTPUT_CHARS	200000	每个 stdout/stderr 的最大返回字符数

本地验证

python3 -m unittest discover -v

不连接 SSH 的协议冒烟测试：

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"1"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | python3 mcp_server.py

实现说明

项目不需要 pip install。MCP 使用一行一个 JSON-RPC 消息的 stdio framing，支持 initialize、ping、tools/list 和 tools/call。远端命令同时受远端 GNU timeout 和本地 SSH 超时保护，默认命令超时 600 秒。