1. 为什么 ClaudeCode 里要接 mcp-ssh-manager

如果你平时用 ClaudeCode 写代码，同时又经常要连远程服务器看日志、传文件、跑部署脚本，那你大概率经历过这种割裂感：一边在编辑器里让 AI 帮你改代码，另一边还得切到终端敲ssh prod-server，再手动scp、tail -f、systemctl restart。AI 完全不知道你服务器上发生了什么，你也没法让它顺手帮你把刚改完的代码推上去。

mcp-ssh-manager 就是来解决这个断层的。它是一个基于 MCP（Model 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 URL

ClaudeCode 本身要连模型服务，mcp-ssh-manager 只是挂在它下面的一个 MCP Server。模型侧我用的是 TaoToken 的接入方式，它兼容 Anthropic 的接口协议，ClaudeCode 可以直接对接。

你需要准备两个值：

• Base URL：https://taotoken.net/api
• API Key：去控制台创建一个，地址是https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite

创建 Key 的入口在 API Keys 页面：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite。点新建，复制那串sk-开头的字符串，只显示一次，丢了就重新建。

模型 ID 这块，ClaudeCode 场景下常用的有claude-sonnet-4-5、claude-opus-4-1这类，具体以你控制台里能选的为准。如果你还没确定用哪个模型，可以先去模型对话页面试一下：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite，发一条消息确认 Key 和模型都通，再回来配 ClaudeCode。

注意：Base URL 后面不要自己加/v1，ClaudeCode 的 Anthropic 兼容层会自己拼路径，加了反而 404。

2.3 确认 ClaudeCode 版本支持 MCP

ClaudeCode 从较早期版本就支持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放你刚创建的 Key，ANTHROPIC_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 再 enable：

claude 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 为PRODUCTION，command 为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_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite确认 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_PROXY：

env | 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 在等输入，Ctrl+C 退出即可，说明路径没问题。

5.5 改了配置不生效

前面提过，MCP 配置改动后必须重载。如果你只改了.mcp.json但没执行 disable/enable，ClaudeCode 用的还是旧配置。养成习惯：改完配置先claude mcp disable ssh-manager再claude mcp enable ssh-manager，然后/mcp确认状态。

5.6 三件套对照表

不管哪种错，配 MCP + 模型接入时始终盯住三件套，缺一个都跑不起来：

MCP 侧同理，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_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite。接入文档在https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite，里面有各语言 SDK 的对接示例。

最后一个实用技巧：mcp-ssh-manager 的 env 里密码字段，别直接写明文。可以在 shell 里 export 一个变量，配置里用${VAR}引用，ClaudeCode 启动时会做变量替换。这样配置文件能安全提交，密码留在本地环境里。