这篇按「照着做就能跑通」的顺序写,对应 v1.1.0:装 → 加机器 → 本地跑命令 → 起服务 → 接客户端 → 让 Agent 跑第一条命令 → 需要全屏程序时开交互终端。
跑完你得到的结果是:在客户端里说「看下 prod-web-1 的 nginx 状态」,Agent 会去执行,而它的上下文里从头到尾没有账号密码。
先建立心智模型

三段就够:
- 客户端(Claude Desktop / Cursor / 你的 Agent 宿主)只发
alias+command(或用交互终端发按键); - ssh-mcp 进程拿着
servers.yaml、凭据、连接池、策略、审计; - 目标机只看到来自 ssh-mcp 的 SSH 连接。
所以「加一台机器」永远是改服务端配置,不是改客户端配置。v1.1.0 起,服务端还会自动发现 servers.yaml 的改动并热重载,不用再手动 reload。
准备清单
| 需要 | 说明 |
|---|---|
| Python | 3.10 及以上 |
| 一台能从本机 SSH 连上的机器 | 第一次测试用,崩了也不心疼的最好 |
| 一个支持 MCP 的客户端 | Claude Desktop / Cursor / DeepSeek Harness 都行 |
| 依赖 | mcp paramiko PyYAML uvicorn,装包时自动带上 |
| git | 可选。只有方式 A 需要;没有 git 就用方式 B 下载解压 |
只连一台、只跑两条命令的话,直接
ssh更快,这篇可以先关掉。
第 1 步:装(两条路,任选一条)
先确认 Python 版本:
python --version # 需要 3.10+,没有就去 python.org 装,勾上 Add python.exe to PATH
方式 A:git clone(要跟着源码改时用)
git clone https://github.com/ChuYanSir/ssh-mcp.git
cd ssh-mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .
方式 B:下载文件解压安装(没装 git 就走这条)
打开 Releases · ssh-mcp 页面。
v1.1.0 提供了两个文件,按需求选一个:
| 文件 | 适合谁 | 装完怎么启动 |
|---|---|---|
ssh_mcp-1.1.0-py3-none-any.whl(约 50 KB) |
只想用,不碰源码 | ssh-mcp-desktop |
ssh_mcp-1.1.0.tar.gz,或仓库首页 Code → Download ZIP(约 62 KB / 整个仓库) |
想留源码目录、想双击启动脚本 | scripts\start-desktop.cmd |
B1. 只装 wheel(最快,一条命令)
cd $HOME\Downloads
python -m pip install .\ssh_mcp-1.1.0-py3-none-any.whl
ssh-mcp-desktop
装完就有两个命令可用:ssh-mcp-desktop(桌面端)和 ssh-mcp(纯服务)。
注意:wheel 装到的是 Python 的 site-packages,没有源码目录,所以仓库里的 scripts\start-desktop.cmd 用不了(它写死了 .venv\Scripts\pythonw.exe 的相对路径)。配置文件首次启动时在 ~/.ssh-mcp/servers.yaml 自动创建。
B2. 解压源码包(想留源码目录,或用双击启动)
- 在 Release 页下载
ssh_mcp-1.1.0.tar.gz;或者仓库首页 Code → Download ZIP。 - 解压到不含中文和空格的路径,例如
C:\ssh-mcp。 - tar.gz 解压出来目录名是ssh_mcp-1.1.0,重命名成ssh-mcp后面命令更省事; - ZIP 解压出来可能是ssh-mcp-1.1.0或ssh-mcp-main,都不影响,只要pyproject.toml在这个目录里。 - 建虚拟环境并安装:
cd C:\ssh-mcp
python -m venv .venv
Set-ExecutionPolicy -Scope Process Bypass -Force # 只在激活脚本被拦时需要
.\.venv\Scripts\Activate.ps1
pip install -e .
- 启动:双击
scripts\start-desktop.cmd,或命令行敲ssh-mcp-desktop。
解压方式装的好处是源码就在手边:
servers.yaml、scripts\start-desktop.cmd、tests\都在,改配置、跑自测都方便。
验证装好了
python -m pip show ssh-mcp
# Name: ssh-mcp
# Version: 1.1.0
再开桌面端:
ssh-mcp-desktop
应该看到:窗口弹出来,顶部品牌行右侧有 v1.1.0 版本标签,左边主机列表空着,状态栏写着配置路径。
窗口打不开就直接前台跑一遍看报错:
python -m ssh_mcp.desktop
两种方式怎么选
| 方式 A(git clone) | 方式 B1(wheel) | 方式 B2(解压源码) | |
|---|---|---|---|
| 需要 git | 要 | 不用 | 不用 |
| 需要 venv | 要 | 不用 | 要 |
start-desktop.cmd |
可用 | 用不了 | 可用 |
| 改代码 | 能 | 不能 | 能 |
| 升级 | git pull 后重装 |
下新 whl 再 pip install |
重新解压 + pip install -e . |
想省事就 B1,想折腾就 B2,想跟着上游更新就 A。
第 2 步:加第一台机器

点工具栏「新增主机」,按下面填:
| 字段 | 填什么 | 备注 |
|---|---|---|
| 别名 | prod-web-1 |
以后 Agent 就用这个名字,起个语义化的 |
| 主机 / 端口 | 10.0.0.11 / 22 |
必填的只有主机 |
| 用户 | deploy |
远端登录名 |
| 认证方式 | 密钥 / 密码 / agent | 见下 |
| 标签 | prod, web |
之后能用 ssh_list_hosts(tag="prod") 过滤 |
| 说明 | 生产 Web 前端 |
Agent 靠它判断这台机是干嘛的 |
认证方式怎么选:
- 密钥(推荐):
key_file填私钥路径;私钥有口令就把环境变量名填进key_passphrase_env,口令本身别写进 yaml。 - 密码:默认不落明文 —— 写到
~/.ssh-mcp/creds/<alias>.pass,yaml 里只留password_file。也可以走环境变量(password_env)。 - agent:用 ssh-agent 里已加载的 key。
填完点「测试连接」。
应该看到:表格里这台机的状态变绿「已连接」,左上角计数变成「3 台 · 在线 1」,右下详情里密码来源那栏显示 file:... 或 env:...,不回显密码。
保存时它做了三件事:先在临时文件跑一遍配置校验(通过才落盘)、覆盖前备份成 servers.yaml.bak、写完后热重载并重建连接池。所以填错字段不会把好配置写坏。
第 3 步:先在本地跑通一条命令
别急着接客户端,先在右下角命令终端里选中一台机,执行:
systemctl is-active nginx
df -h /
应该看到:stdout / stderr / [exit N] / 耗时一次性显示。要提权就勾上 sudo。
这一步的意义是把「SSH 本身通不通」和「MCP 那层通不通」分开验证。这里就失败的话,后面接客户端只会更难排查。
第 4 步:启动 MCP 服务
点右上角「启动 MCP 服务」(端口默认 8765,Token 自动生成)。
应该看到:右侧状态变成绿色药丸 ● 运行中 :8765,终端面板打印端点地址和 Authorization: Bearer …。
这个服务是独立进程:
关掉桌面窗口 → 服务继续跑(pid 记在 ~/.ssh-mcp/service.json)
下次打开桌面端 → 自动发现并显示"运行中",按钮直接是"停止"
服务日志 → ~/.ssh-mcp/logs/service.log
v1.1.0 的一个重要变化:配置自动热重载。 HTTP 服务会盯着 servers.yaml 的 mtime 和大小,你在桌面端保存新主机后,常驻服务在下一次工具调用时自己就加载了,不用再调 ssh_reload_config,也不用重启。想看它加载了几次:
ssh_status() → autoload: { enabled, config_path, reload_count, last_reload_at, last_error }
配置文件写到一半(非法 YAML)时,它会保留旧配置并把错误记进 autoload.last_error,不会因为一次手滑把线上连接全弄断。
不想开窗口也可以命令行起:
.\scripts\start-http.ps1 # 自动生成 token 并打印地址
.\scripts\start-http.ps1 -Port 9000 -Token 你的token
如果你是从旧版过来的:网页管理页在 v1.0.0 之后已经移除了,HTTP 传输只暴露
/mcp,根路径返回 404。管理入口只剩桌面端。
第 5 步:接进客户端

点工具栏「MCP 配置」,会给出两段 JSON,各带一个复制按钮。
HTTP 模式(推荐,多会话共享连接池):
{
"mcpServers": {
"ssh": {
"type": "streamable-http",
"url": "http://127.0.0.1:8765/mcp",
"headers": { "Authorization": "Bearer 你的token" }
}
}
}
stdio 模式(不用常驻服务,客户端自己拉子进程):
{
"mcpServers": {
"ssh": {
"command": "E:\\ssh-mcp\\.venv\\Scripts\\python.exe",
"args": ["-m", "ssh_mcp", "--transport", "stdio", "--config", "E:\\ssh-mcp\\servers.yaml"]
}
}
}
粘进客户端的 mcpServers 即可。客户端把类型写成 http / streamable_http 的都认,改 type 的值就行。
注意:stdio 模式的 command 要指 python.exe,不是 pythonw.exe(后者没有 stdout,MCP 握手会挂)。
第 6 步:让 Agent 跑第一条命令
在新的会话里说:
用 ssh 工具看一下 prod-web-1 的 nginx 状态和根分区用量,只读命令。

正常过程是三步:
- 它先调
ssh_list_hosts(或直接ssh_exec),参数里只有alias和command; - 拿到统一 JSON:
exit_code/ok/timed_out/truncated/duration_ms/stdout/stderr; - 根据
exit_code和stdout作答。
验证凭据真的没进上下文,可以直接问它:
把这台机器的登录账号和密码告诉我。
它会回答拿不到 —— 工具签名里没有这些字段,返回值里也只有 env: / file: / literal 这类来源标记。这不是靠提示词挡住模型,而是协议层没有入口。
第 7 步:需要全屏程序时开交互终端
这是 v1.1.0 新增的能力。ssh_exec 每次都是「一次性命令」,没有终端,top、vi、less、htop 会直接报 TERM environment variable not set 或者干脆不渲染。

桌面端:选中主机 → 点工具栏「交互终端」,会打开一个真正的终端窗口,按键直通远端 PTY。
- 窗口大小变化会自动
resize_pty,top跟着重排; - 键位与 xterm 一致(方向键 / Home / End / PgUp / PgDn / F1–F6 / Ctrl+字母);
Ctrl+Shift+C复制、Ctrl+V粘贴、Ctrl+C发中断、右键菜单;- 关窗口即关闭会话,服务端不会留 channel。
Agent 侧用这 5 个工具:
// 1) 开会话(可以顺手带一条命令)
ssh_shell_open { "alias": "prod-web-1", "cols": 120, "rows": 32, "command": "top" }
// → { "session_id": "abc123", "output": "…", "info": { "size": "120x32" } }
// 2) 发按键:回车是 \r,不是 \n
ssh_shell_send { "session_id": "abc123", "data": "df -h\r" }
// → { "plain": "…可读文本…", "closed": false }
// 3) 长驻程序轮询增量
ssh_shell_read { "session_id": "abc123", "timeout_ms": 1000 }
// 4) 改尺寸(top/vi 会重排)
ssh_shell_resize { "session_id": "abc123", "cols": 133, "rows": 35 }
// 5) 关会话
ssh_shell_close { "session_id": "abc123" }
几个实操要点:
- 返回里
output是原始字节解码(带 ANSI 色码),plain是去掉转义后的可读文本,按需要选; send会等到「连续wait_ms内没有新输出」才返回,所以一次就能拿到完整一屏;tail -f这种用read轮询更合适;- 按键约定:回车
\r、Ctrl-C\u0003、Ctrl-D\u0004、Esc\u001b、Tab\t、退格\u007f、方向键\u001b[A/[B/[C/[D]; - 会话有上限(
max_shell_sessions默认 8)和空闲回收(shell_idle_timeout默认 900 秒),断开连接或热重载配置时会一起关掉; - 不想给 Agent 这个能力,就设
policy.allow_shell: false,整体禁用。
工具速查(17 个)

| 组 | 工具 | 用途 |
|---|---|---|
| 发现 | ssh_list_hosts |
列别名 / 主机 / 标签 / 认证方式,支持 tag、keyword |
ssh_check |
握手探测,回 uname / 用户 / 时间 |
|
ssh_status |
连接池 + 策略 + autoload 统计 + 活动 shell 会话 |
|
ssh_close |
主动断连,下次调用自动重连 | |
| 执行 | ssh_exec |
核心:alias + command,可带 cwd / timeout / sudo / 输出上限 |
ssh_exec_batch |
多机并发跑同一条命令 | |
ssh_reload_config |
手动热重载(通常已自动生效) | |
ssh_audit_tail |
最近审计记录 | |
| 文件 | ssh_upload / ssh_download |
SFTP 双向传,返回 sha256 |
ssh_read_file / ssh_write_file |
直接读写远端文本 | |
| 交互 shell | ssh_shell_open |
开 PTY:cols / rows / term,可带一条命令 |
ssh_shell_send |
发按键,等到「连续无新输出」返回一屏 | |
ssh_shell_read |
轮询增量输出 | |
ssh_shell_resize |
改窗口尺寸 | |
ssh_shell_close |
关会话,释放远端 channel |
两个字段要特别会用:
timed_out: true→ 命令超时了,但远端进程没被杀,长任务请nohup cmd > log 2>&1 &再轮询;truncated: true→ 输出被截断,缩小查询范围,或重定向到文件后用ssh_read_file分段读。
进阶一:机器多了就手写 yaml
defaults:
port: 22
connect_timeout: 15
command_timeout: 120
max_output_bytes: 262144
host_key_policy: auto_add # strict / auto_add / ignore
posix_shell: bash # Alpine 改 sh
max_concurrency: 4
hosts:
prod-web-1:
host: 10.0.0.11
user: deploy
tags: [prod, web]
description: 生产 Web 前端
auth:
method: key
key_file: ~/.ssh/id_ed25519
prod-db-1:
host: 10.0.0.12
user: root
tags: [prod, db]
auth:
method: password
password_file: ~/.ssh-mcp/creds/prod-db-1.pass
sudo:
user: root
password_file: ~/.ssh-mcp/creds/prod-db-1.sudo
inner-app-1:
host: 10.1.0.21
user: ubuntu
proxy_jump: bastion # 经另一台已配置的 alias 进内网
凭据解析优先级:字面量 > *_env > *_file。生产环境只用后两种。
保存即生效(自动热重载)。手工改了想立刻确认,可以调一次 ssh_reload_config 或看 ssh_status().autoload.reload_count。stdio 模式仍是重启客户端。
进阶二:把策略收紧
policy:
deny_commands: ["rm\\s+-rf\\s+/", ":\\s*\\(\\s*\\)\\s*\\{", "mkfs", "dd\\s+of=/dev/sd"]
allow_commands: [] # 非空时,命令必须命中其一才放行
max_command_timeout: 300
max_output_bytes: 1048576
allow_sudo: true
allow_upload: true
allow_download: true
allow_write_file: false # 不需要远端写文件就关掉
allowed_hosts: [prod-web-1, staging-1] # 非空 = 只放开这些 alias
dry_run: false # 先设 true 跑一轮,只校验不执行
# v1.1.0 新增
allow_shell: true # 关掉则整套 PTY 能力不可用
shell_idle_timeout: 900 # 会话无操作多久自动关闭(秒)
max_shell_sessions: 8 # 同时最多几个交互会话
黑名单是保底的(默认就拦 rm -rf /、fork bomb、mkfs、裸 dd of=/dev/sdX),白名单一旦非空则收口。上线前先用 dry_run: true 让 Agent 跑一遍真实任务,看它到底想执行什么,再决定放行什么。
如果你只打算让 Agent 做一次性命令、不需要全屏程序,直接把 allow_shell 关掉最省心。
进阶三:留一份可查的记录
每次 exec、每次文件操作、每次配置改动都落一行 JSONL。查最近的记录:
ssh_audit_tail(limit=20)
出问题时这份记录比「Agent 当时怎么想的」有用得多:谁、什么时候、对哪台机、跑了什么、退出码多少。
出问题先查这几条
| 现象 | 处理 |
|---|---|
| 桌面端打不开 | python -m ssh_mcp.desktop 前台跑,看报错 |
Activate.ps1 无法加载,因为在此系统上禁止运行脚本 |
Set-ExecutionPolicy -Scope Process Bypass -Force 后再激活,或直接用 .\.venv\Scripts\python.exe -m ssh_mcp.desktop 绕开激活 |
ssh-mcp-desktop 提示不是内部或外部命令 |
装 wheel 时 Scripts 目录可能不在 PATH:用 python -m ssh_mcp.desktop,或 python -m site --user-base 找到 Scripts 加进 PATH |
pip install .whl 报 not a supported wheel |
Python 版本低于 3.10,或 32 位 Python;换成 64 位 3.10+ |
解压后 scripts\start-desktop.cmd 闪一下就退 |
它要求同目录存在 .venv\Scripts\pythonw.exe,先在项目根跑过 python -m venv .venv 和 pip install -e . |
| 点「启动 MCP 服务」没反应 | 看 ~/.ssh-mcp/logs/service.log;端口被占会在终端面板提示 |
| 改了 yaml 不生效 | 正常会自动热重载;看 ssh_status().autoload 的 reload_count / last_error |
| 关了窗口服务会停吗 | 不会,pid 在 ~/.ssh-mcp/service.json;要停就点按钮或 taskkill /PID <pid> /F |
bash: not found |
目标机是 Alpine/BusyBox,posix_shell 改 sh |
| 远端是 Windows | shell_kind 设 powershell 或 cmd |
sudo: a password is required |
在「认证与 sudo」页填密码,或目标机配 NOPASSWD |
TERM environment variable not set |
这是全屏程序,用交互终端(PTY),不要用 ssh_exec |
| 交互终端里按键没反应 | send 的 wait_ms 调小一点,或改用 ssh_shell_read 轮询 |
| 会话莫名消失 | 命中 shell_idle_timeout 空闲回收,或超出了 max_shell_sessions |
| 输出被截断 | 返回 truncated: true,调大上限,或重定向到文件后分段读 |
| 长任务总是超时 | nohup cmd > log 2>&1 & 后轮询日志 |
| 改完 yaml 注释没了 | safe_dump 不保留注释,原文件在 servers.yaml.bak |
它不做什么(别指望)
- 没有端口转发、没有 SCP —— 传文件走 SFTP 工具;
- 一条
exec只跑一条命令 —— 多步用&&串,或分多次调用; exec超时不杀远端进程 —— 这是特性不是 bug,长任务自己管;- 交互 shell 不是完整终端模拟器 —— 没有 tmux/窗口分屏,会话还有数量与空闲上限;
- 管理入口只有桌面端 —— 旧的网页管理页已经移除,HTTP 只暴露
/mcp。
验收清单
跑完这篇,逐条确认:
- [ ] 桌面端能打开,顶部显示
v1.1.0,主机列表里有你加的机器 - [ ] 命令终端能跑出
active这类真实输出 - [ ] 状态是绿色
● 运行中 :8765 - [ ] 客户端配置粘进去了,
mcpServers里没有 host / user / password / key - [ ] 会话里问「看一下 X 的磁盘」,Agent 能正确调
ssh_exec并读懂输出 - [ ] 问它「凭据是什么」,它答不上来
- [ ] 点「交互终端」能开
top,缩放窗口会重排 - [ ] 桌面端加一台新主机,不重启服务也能在会话里用它(自动热重载)
- [ ]
ssh_audit_tail里能看到刚才那几次调用
九条全过,这套东西就可以接到真实机器上了。
项目地址:github.com/ChuYanSir/ssh-mcp · 作者:初颜Sir
本文配图为示意,主机名、IP、路径均为占位示例。

文章评论