ClaudeCode 配置 mcp-ssh-manager：settings.json 骨架与连通性验证

1. 为什么 ClaudeCode 里要接 mcp-ssh-manager如果你平时用 ClaudeCode 写代码同时又经常要连远程服务器看日志、传文件、跑部署脚本那你大概率经历过这种割裂感一边在编辑器里让 AI 帮你改代码另一边还得切到终端敲ssh prod-server再手动scp、tail -f、systemctl restart。AI 完全不知道你服务器上发生了什么你也没法让它顺手帮你把刚改完的代码推上去。mcp-ssh-manager 就是来解决这个断层的。它是一个基于 MCPModel Context Protocol的 SSH 连接管理工具把「连服务器」这件事抽象成一组 ClaudeCode 能调用的工具函数。配置好之后你可以在对话框里直接说「列出我所有服务器」「连到 production 看下 nginx 错误日志」ClaudeCode 会通过 MCP 通道调用 mcp-ssh-manager再由它去执行真正的 SSH 操作。它适合谁三类人最明显一是手上管着三五台甚至十几台服务器的后端/运维开发者二是做私有化部署、需要频繁在测试机和生产机之间切换的人三是想让 AI Agent 参与部署流程、但又不想把 SSH 密码明文写进脚本的人。mcp-ssh-manager 支持在环境变量里集中管理多台服务器的别名、地址、端口、认证方式ClaudeCode 只需要知道别名就能操作省掉了每次手敲 IP 的重复劳动。我试过在 MacOS 上从零配一遍整体流程不复杂但有几个坑点index.js 的绝对路径容易写错、环境变量命名有固定格式、改完配置必须 disable 再 enable 才生效。这篇就把 settings.json 骨架、启动参数、连通性验证动作完整走一遍你照着复制改改就能用。2. 前置准备装好 mcp-ssh-manager 并拿到 TaoToken Key在动 ClaudeCode 的配置文件之前先把两件事做完装 mcp-ssh-manager以及准备好模型侧的接入凭证。2.1 安装 mcp-ssh-manager官方包在 npm 上全局装一条命令就够npm install -g mcp-ssh-manager装完之后确认一下入口文件位置。MacOS 上用 Homebrew 装的 Node全局包一般在/opt/homebrew/lib/node_modules/下面Linux 或 Windows 的路径会不一样你可以用这条命令查npm root -g假设输出是/opt/homebrew/lib/node_modules那 mcp-ssh-manager 的入口就是/opt/homebrew/lib/node_modules/mcp-ssh-manager/src/index.js这个绝对路径后面要写进配置先记下来。如果你不想写死路径也可以用npx方式启动配置里 command 写npx、args 写包名即可但 npx 每次启动会做一次解析首次调用会慢几秒长期用还是建议写绝对路径。2.2 准备 TaoToken 的 API Key 和 Base URLClaudeCode 本身要连模型服务mcp-ssh-manager 只是挂在它下面的一个 MCP Server。模型侧我用的是 TaoToken 的接入方式它兼容 Anthropic 的接口协议ClaudeCode 可以直接对接。你需要准备两个值Base URLhttps://taotoken.net/apiAPI Key去控制台创建一个地址是https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite创建 Key 的入口在 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite。点新建复制那串sk-开头的字符串只显示一次丢了就重新建。模型 ID 这块ClaudeCode 场景下常用的有claude-sonnet-4-5、claude-opus-4-1这类具体以你控制台里能选的为准。如果你还没确定用哪个模型可以先去模型对话页面试一下https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite发一条消息确认 Key 和模型都通再回来配 ClaudeCode。注意Base URL 后面不要自己加/v1ClaudeCode 的 Anthropic 兼容层会自己拼路径加了反而 404。2.3 确认 ClaudeCode 版本支持 MCPClaudeCode 从较早期版本就支持claude mcp add命令你可以先跑一下确认claude mcp --help能看到add、list、remove这些子命令就说明没问题。如果提示 command not found先升级 ClaudeCode 到最新版。3. settings.json 骨架与 mcp-ssh-manager 启动参数这一节是核心把配置文件的完整骨架给出来包括 ClaudeCode 的模型接入配置和 mcp-ssh-manager 的 MCP Server 定义。3.1 ClaudeCode 的 settings.json 模型接入部分ClaudeCode 读取的配置文件在用户目录下路径是~/.claude/settings.json。如果你之前没建过直接新建一个。模型接入相关的字段长这样{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-5 } }三个字段的作用分别是ANTHROPIC_BASE_URL指向 TaoToken 的 API 入口ANTHROPIC_AUTH_TOKEN放你刚创建的 KeyANTHROPIC_MODEL指定默认调用的模型 ID。这三个必须同时存在缺一个 ClaudeCode 启动时会报认证或模型找不到的错。3.2 mcp-ssh-manager 的 MCP Server 定义MCP Server 的配置有两种放法项目级和用户级。项目级会在项目根目录生成.mcp.json只对当前项目生效用户级写在~/.claude.json里全局生效。推荐项目级隔离性好换项目不会互相干扰。在项目根目录执行claude mcp add ssh-manager --scope project node /opt/homebrew/lib/node_modules/mcp-ssh-manager/src/index.js执行完项目下会多一个.mcp.json默认内容{ mcpServers: { ssh-manager: { type: stdio, command: node, args: [ /opt/homebrew/lib/node_modules/mcp-ssh-manager/src/index.js ], env: {} } } }如果你不想写绝对路径可以改成 npx 启动{ mcpServers: { ssh-manager: { type: stdio, command: npx, args: [ iflow-mcp/mcp-ssh-manager ], env: {}, trust: true } } }trust: true表示信任这个 Server不会每次启动都弹确认。3.3 环境变量多台服务器的别名配置mcp-ssh-manager 的服务器信息全部通过env字段传入命名有固定格式。单台服务器的写法{ mcpServers: { ssh-manager: { type: stdio, command: node, args: [ /opt/homebrew/lib/node_modules/mcp-ssh-manager/src/index.js ], env: { SSH_SERVER_PRODUCTION_HOST: 192.168.1.100, SSH_SERVER_PRODUCTION_PORT: 22, SSH_SERVER_PRODUCTION_USER: deploy, SSH_SERVER_PRODUCTION_PASSWORD: 你的密码 } } } }PRODUCTION是服务器别名你可以随便命名但同一个别名下的 HOST、PORT、USER、PASSWORD 必须成套出现。多台服务器就换别名再写一组env: { SSH_SERVER_PRODUCTION_HOST: 192.168.1.100, SSH_SERVER_PRODUCTION_PORT: 22, SSH_SERVER_PRODUCTION_USER: deploy, SSH_SERVER_PRODUCTION_PASSWORD: prod密码, SSH_SERVER_KVMHADOOP_HOST: 10.0.0.21, SSH_SERVER_KVMHADOOP_PORT: 22, SSH_SERVER_KVMHADOOP_USER: hadoop, SSH_SERVER_KVMHADOOP_PASSWORD: hadoop密码 }如果你用密钥认证把PASSWORD换成PRIVATE_KEY_PATH值是私钥文件的绝对路径比如/Users/you/.ssh/id_rsa。两种认证方式不要同时配会冲突。3.4 启动参数说明mcp-ssh-manager 本身不需要额外命令行参数所有配置都走环境变量。但有几个点要注意type固定写stdio因为 ClaudeCode 通过标准输入输出和 MCP Server 通信。command和args拼起来就是完整的启动命令等价于在终端跑node /path/to/index.js。env里的变量会注入到子进程环境里mcp-ssh-manager 启动时读取这些变量构建服务器列表。改完配置后ClaudeCode 不会自动重载 MCP Server。你需要先 disable 再 enableclaude mcp disable ssh-manager claude mcp enable ssh-manager或者直接重启 ClaudeCode 会话。这一步很多人会漏改完配置发现没生效八成是没重载。4. 验证请求一条命令确认 MCP 通道生效配置写完重载完接下来验证。验证分两层先确认 MCP Server 本身起来了再确认 SSH 连通性。4.1 查看 MCP Server 状态在 ClaudeCode 对话框里输入/mcp会列出当前会话加载的所有 MCP Server。找到ssh-manager状态应该是connected。如果显示failed或disconnected说明启动命令有问题去检查 index.js 路径是否正确、Node 是否在 PATH 里。4.2 调用 ssh_list_servers 列出服务器mcp-ssh-manager 暴露的工具函数命名规则是mcp__server名__工具名。列出服务器的工具是ssh_list_servers所以在对话框里输入mcp__ssh-manager__ssh_list_servers如果配置正确ClaudeCode 会返回你刚才在 env 里配的所有服务器别名和基本信息类似Available SSH servers: - PRODUCTION (192.168.1.100:22, user: deploy) - KVMHADOOP (10.0.0.21:22, user: hadoop)看到这个列表说明 MCP 通道已经打通ClaudeCode 能正常调用 mcp-ssh-manager 了。4.3 执行一次真实 SSH 连通性验证光列出服务器还不够得实际连一次确认认证没问题。用ssh_exec工具在目标服务器上跑一条无害命令mcp__ssh-manager__ssh_exec参数里指定 server 为PRODUCTIONcommand 为echo mcp-ssh-ok hostname。如果返回类似mcp-ssh-ok prod-web-01说明 SSH 认证、命令执行、结果回传整条链路都通了。这一步很关键因为有些环境里服务器列表能列出来但实际连接时因为密码错、端口不通、防火墙拦截而失败只有真正执行命令才能暴露。4.4 让 ClaudeCode 用自然语言操作验证通过后你就可以用自然语言指挥了。比如连到 PRODUCTION看下 /var/log/nginx/error.log 最后 50 行ClaudeCode 会自动调用ssh_exec把tail -n 50 /var/log/nginx/error.log发到 PRODUCTION 上执行再把结果贴回来。你不需要记工具名AI 会根据你的意图选对应的 MCP 工具。5. 常见报错排查401、local proxy failed、reading choices配置过程中最容易撞的几个错我按实际遇到的频率排一下。5.1 401 Unauthorized这个错一般出在模型侧不是 MCP 侧。原因是ANTHROPIC_AUTH_TOKEN填错了或者 Key 被删了。排查步骤先去https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite确认 Key 还在然后检查 settings.json 里有没有多余空格或换行。Key 是sk-开头的一整串复制时别漏字符。如果 Key 没问题还是 401检查ANTHROPIC_BASE_URL是不是写成了https://taotoken.net/api/末尾多了斜杠有些版本会因此拼出双斜杠导致认证失败。改成不带末尾斜杠的https://taotoken.net/api。5.2 local proxy failed这个错通常出现在 ClaudeCode 启动阶段提示本地代理连接失败。原因是 ClaudeCode 尝试走系统代理但代理配置有问题。如果你没主动配代理检查环境变量里有没有残留的HTTP_PROXY、HTTPS_PROXYenv | grep -i proxy有的话 unset 掉再启动 ClaudeCode。另外确认ANTHROPIC_BASE_URL是直连地址不要指向本地某个端口。5.3 reading choices 相关报错这个错一般长这样error reading choices: unexpected end of JSON input。它出在 MCP Server 返回的数据格式不对常见原因是 mcp-ssh-manager 启动时 env 里的服务器配置不完整比如只写了 HOST 没写 USER导致内部构建服务器对象时抛异常返回了空响应。排查方法把 env 里每个别名的 HOST、PORT、USER、PASSWORD或 PRIVATE_KEY_PATH四项都补齐缺一不可。补完 disable/enable 重载。5.4 MCP Server 显示 failed 但没具体报错这种情况多半是 index.js 路径写错了。手动在终端跑一下配置里的完整命令node /opt/homebrew/lib/node_modules/mcp-ssh-manager/src/index.js如果提示Cannot find module说明路径不对用npm root -g重新确认。如果命令能跑起来但卡住不动那是正常的stdio 类型的 Server 在等输入CtrlC 退出即可说明路径没问题。5.5 改了配置不生效前面提过MCP 配置改动后必须重载。如果你只改了.mcp.json但没执行 disable/enableClaudeCode 用的还是旧配置。养成习惯改完配置先claude mcp disable ssh-manager再claude mcp enable ssh-manager然后/mcp确认状态。5.6 三件套对照表不管哪种错配 MCP 模型接入时始终盯住三件套缺一个都跑不起来组件字段值示例Base URLANTHROPIC_BASE_URLhttps://taotoken.net/apiAPI KeyANTHROPIC_AUTH_TOKENsk-xxxxModel IDANTHROPIC_MODELclaude-sonnet-4-5MCP 侧同理Server 名、启动命令、env 里的服务器四元组也是缺一不可。排查时先确认这三件套齐全再去查网络和路径。6. 把 MCP 通道用起来从验证到日常操作连通性验证通过只是起点真正省时间的是把它嵌进日常流程。我现在的习惯是项目根目录的.mcp.json跟着代码一起提交到仓库密码字段用环境变量引用不写明文团队里每个人拉下来就能用同一套服务器别名。ClaudeCode 在项目里打开时自动加载这个配置不需要每人手动 add。日常操作里最高频的三个场景看日志、传文件、重启服务。看日志直接说「连 PRODUCTION 看 xxx 日志最后 100 行」传文件说「把本地 dist 目录同步到 PRODUCTION 的 /var/www/html」重启服务说「在 PRODUCTION 上重启 nginx」。ClaudeCode 会自己选对应的 MCP 工具执行。如果你要长期跑 Agent 任务比如让 AI 自动部署、自动巡检建议把模型侧切到 Coding Plan额度更稳适合高频调用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有各语言 SDK 的对接示例。最后一个实用技巧mcp-ssh-manager 的 env 里密码字段别直接写明文。可以在 shell 里 export 一个变量配置里用${VAR}引用ClaudeCode 启动时会做变量替换。这样配置文件能安全提交密码留在本地环境里。