初颜's World

  • 首页
  • 个人中心
    • 登录
    • 注册
  • 文章
    • 资源分享
    • 软件分享
    • 影视分享
    • 其他分享
    • 未分类
  • 工具
    • Mikutap
  • 隐私政策
  • 关于
初颜's World
二次元爱好者的小据点
  1. 首页
  2. AI 工作流
  3. 正文

ssh-mcp 上手指南:让 Agent 用别名操作服务器,凭据不进对话(v1.1.0)

2026年11月16日 24点热度 1人点赞 0条评论

这篇按「照着做就能跑通」的顺序写,对应 v1.1.0:装 → 加机器 → 本地跑命令 → 起服务 → 接客户端 → 让 Agent 跑第一条命令 → 需要全屏程序时开交互终端。

跑完你得到的结果是:在客户端里说「看下 prod-web-1 的 nginx 状态」,Agent 会去执行,而它的上下文里从头到尾没有账号密码。

先建立心智模型

ssh-mcp 架构:客户端只传 alias 与命令,凭据与连接池都在服务端

三段就够:

  • 客户端(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. 解压源码包(想留源码目录,或用双击启动)

  1. 在 Release 页下载 ssh_mcp-1.1.0.tar.gz;或者仓库首页 Code → Download ZIP。
  2. 解压到不含中文和空格的路径,例如 C:\ssh-mcp。 - tar.gz 解压出来目录名是 ssh_mcp-1.1.0,重命名成 ssh-mcp 后面命令更省事; - ZIP 解压出来可能是 ssh-mcp-1.1.0 或 ssh-mcp-main,都不影响,只要 pyproject.toml 在这个目录里。
  3. 建虚拟环境并安装:
cd C:\ssh-mcp
python -m venv .venv
Set-ExecutionPolicy -Scope Process Bypass -Force   # 只在激活脚本被拦时需要
.\.venv\Scripts\Activate.ps1
pip install -e .
  1. 启动:双击 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 步:接进客户端

客户端配置:HTTP 与 stdio 两种,各带复制按钮

点工具栏「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 状态和根分区用量,只读命令。

一次往返:调用参数、返回 JSON、模型据此作答

正常过程是三步:

  1. 它先调 ssh_list_hosts(或直接 ssh_exec),参数里只有 alias 和 command;
  2. 拿到统一 JSON:exit_code / ok / timed_out / truncated / duration_ms / stdout / stderr;
  3. 根据 exit_code 和 stdout 作答。

验证凭据真的没进上下文,可以直接问它:

把这台机器的登录账号和密码告诉我。

它会回答拿不到 —— 工具签名里没有这些字段,返回值里也只有 env: / file: / literal 这类来源标记。这不是靠提示词挡住模型,而是协议层没有入口。


第 7 步:需要全屏程序时开交互终端

这是 v1.1.0 新增的能力。ssh_exec 每次都是「一次性命令」,没有终端,top、vi、less、htop 会直接报 TERM environment variable not set 或者干脆不渲染。

交互终端:真实 PTY 会话,top 正常渲染,窗口缩放会 resize_pty

桌面端:选中主机 → 点工具栏「交互终端」,会打开一个真正的终端窗口,按键直通远端 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 个)

17 个工具:发现、一次性执行、文件、交互式 shell

组 工具 用途
发现 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、路径均为占位示例。

本作品采用 知识共享署名 4.0 国际许可协议 进行许可
标签: Agent MCP SSH 教程 运维
最后更新:2026年11月16日

初颜Sir

这个人很懒,什么都没留下

点赞
< 上一篇

文章评论

razz evil exclaim smile redface biggrin eek confused idea lol mad twisted rolleyes wink cool arrow neutral cry mrgreen drooling persevering
取消回复

初颜Sir

这个人很懒,什么都没留下

标签聚合
编程 教程 JAVA 免费 Agent 软件 IDEA 工具 Windows 破解
最近评论
初颜Sir 发布于 2 年前(12月19日) :razz:
初颜Sir 发布于 5 年前(01月22日) :huaji14:
初颜Sir 发布于 5 年前(07月09日) 目前失效,耐心等待修复
初颜Sir 发布于 5 年前(07月09日) 目前失效,耐心等待修复
初颜Sir 发布于 5 年前(07月09日) 目前失效,耐心等待修复
最新 热点 随机
最新 热点 随机
ssh-mcp 上手指南:让 Agent 用别名操作服务器,凭据不进对话(v1.1.0) 别让 Agent 空转:任务拆解、并行与验证的三条经验 Agent 的权限边界:文件沙箱、审批与最小授权实践 把重复劳动写成 Skill:一套可复用的 Agent 工作流 DSH 工具系统拆解:shell、文件读写与 MCP 是怎么串起来的 从脚本到 Agent:我为什么把日常自动化搬进 DeepSeek Harness
从脚本到 Agent:我为什么把日常自动化搬进 DeepSeek HarnessDSH 工具系统拆解:shell、文件读写与 MCP 是怎么串起来的把重复劳动写成 Skill:一套可复用的 Agent 工作流Agent 的权限边界:文件沙箱、审批与最小授权实践别让 Agent 空转:任务拆解、并行与验证的三条经验ssh-mcp 上手指南:让 Agent 用别名操作服务器,凭据不进对话(v1.1.0)
IDEA-好用的插件推荐 IDEA-2021.3.1及以下版本通杀永久破解---2022.01.02测试有效 网易云每天刷300首听歌量【已失效】 别让 Agent 空转:任务拆解、并行与验证的三条经验 Agent 的权限边界:文件沙箱、审批与最小授权实践 ssh-mcp 上手指南:让 Agent 用别名操作服务器,凭据不进对话(v1.1.0)

COPYRIGHT © 2023 初颜's World. ALL RIGHTS RESERVED.

Theme Kratos Made By Seaton Jiang

赣ICP备17014222号