mcp-ssh
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-ssh connect to server-01 and run 'df -h'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP SSH Server
一个基于 expect + Python MCP 的 SSH 持久连接方案,专为 JumpServer 堡垒机设计。
解决传统 SSH MCP 工具无法通过交互式堡垒机保持长连接的问题。
特性
多堡垒机支持 - 一个配置文件管理多台 JumpServer 和多台目标服务器
持久长连接 - 每个连接对应独立 expect 子进程,长期存活无需反复鉴权
并发执行 - 同时连接多台服务器,各自独立互不干扰
热加载 - 修改配置或模板后无需重启,下次调用自动生效
双认证模式 - 支持 SSH 密钥和密码两种认证方式
快速响应 - 使用 marker 分割技术,命令执行后立即返回输出
Related MCP server: mcp-jumpserver-gui-sucks
架构
┌─────────────────────────────────────────────────────────────┐
│ Claude Code / MCP Client │
└──────────────────────────┬──────────────────────────────────┘
│ stdio JSON-RPC
▼
┌─────────────────────────────────────────────────────────────┐
│ MCP SSH Server (Python) │
│ ┌──────────────────┐ ┌──────────────────────────────┐ │
│ │ SessionManager │ │ config.json (热加载) │ │
│ │ ├─ connect() │◄──►│ bastions[] → servers[] │ │
│ │ ├─ execute() │ └──────────────────────────────┘ │
│ │ └─ close() │ │
│ └────────┬─────────┘ │
│ │ spawn + pipe │
│ ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ expect_template.py (热加载) │ │
│ │ 生成 expect 脚本处理交互式认证 │ │
│ └────────┬─────────────────────────────────────────────┘ │
└───────────┼──────────────────────────────────────────────────┘
│ spawn expect
▼
┌─────────────────────────────────────────────────────────────┐
│ expect 进程 (per session) │
│ ┌─────────────────┐ │
│ │ spawn ssh │──→ JumpServer → 目标服务器 │
│ │ stdin pipe │◄── 接收 Python 发来的命令 │
│ │ stdout pipe │── 输出到 Python reader 线程 │
│ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘安装
前置要求
Python 3.10+
expect (系统命令)
uv (推荐的 Python 包管理器)
安装 expect
macOS:
brew install expectUbuntu/Debian:
sudo apt-get install expectCentOS/RHEL:
sudo yum install expect安装项目
cd a-mcp/mcp-ssh
uv sync配置
复制配置示例并修改:
cp config.example.json config.json配置示例
{
"bastions": [
{
"id": "bastion-01",
"host": "bastion.example.com",
"port": 22,
"user": "your_username",
"auth_type": "key",
"key_path": "~/.ssh/your_key.pem",
"password": "",
"default": true,
"servers": [
{
"id": "server-01",
"name": "应用服务器 1",
"search": "/192.168.1.100",
"asset_id": "1",
"target_dir": "/var/www/app1"
},
{
"id": "server-02",
"name": "应用服务器 2",
"search": "/192.168.1.101",
"asset_id": "2",
"target_dir": "/var/www/app2"
}
]
},
{
"id": "direct-server",
"host": "direct.example.com",
"port": 22,
"user": "your_username",
"auth_type": "password",
"key_path": "",
"password": "your_password",
"default": false,
"servers": []
}
]
}配置说明
字段 | 类型 | 说明 |
| string | 唯一标识符 |
| string | 服务器地址 |
| int | SSH 端口(默认 22) |
| string | 用户名 |
| string | 认证方式: |
| string | SSH 私钥路径( |
| string | 密码( |
| bool | 是否为默认堡垒机 |
| array | 该堡垒机下的目标服务器列表 |
服务器配置 (servers[]):
字段 | 类型 | 说明 |
| string | 服务器唯一 ID(用于 |
| string | 服务器名称(描述用) |
| string | JumpServer 搜索关键词(如 |
| string | JumpServer 资产 ID |
| string | 登录后切换的工作目录 |
使用方法
作为 MCP 服务
在 Claude Code 或其他 MCP 客户端中配置:
{
"mcpServers": {
"ssh": {
"command": "uv",
"args": ["run", "--directory", "/path/to/mcp-ssh", "python", "mcp_ssh_server.py"]
}
}
}MCP 工具列表
工具 | 说明 |
| 通过配置连接服务器(推荐) |
| 直接指定参数连接(临时使用) |
| 在会话中执行命令 |
| 读取会话缓冲区输出 |
| 关闭会话 |
| 列出所有活跃会话 |
| 列出配置中的所有服务器 |
使用示例
1. 连接服务器
# 使用配置中的服务器 ID
ssh_connect(server_id="server-01")
# 或直接指定参数
ssh_connect_raw(
host="example.com",
port=22,
user="admin",
password="secret",
search="", # 直连模式
target_dir="/home/admin"
)2. 执行命令
ssh_execute(session_id="session_1", command="ls -la")
ssh_execute(session_id="session_1", command="df -h")3. 管理会话
# 查看所有活跃会话
ssh_list_sessions()
# 关闭指定会话
ssh_close(session_id="session_1")项目结构
mcp-ssh/
├── mcp_ssh_server.py # MCP 服务主入口 + SessionManager
├── expect_template.py # expect 脚本模板(支持热加载)
├── config.json # 多堡垒机 + 多资产配置(需自行创建)
├── config.example.json # 配置示例
├── pyproject.toml # Python 项目配置
├── uv.lock # 依赖锁定
├── ARCHITECTURE.md # 详细架构文档
└── README.md # 本文件开发指南
本地测试
cd a-mcp/mcp-ssh
uv run python mcp_ssh_server.py热加载机制
config.json - 每次调用
ssh_connect或ssh_list_servers时检查修改时间,变更则重新加载expect_template.py - 每次生成 expect 脚本时检查修改时间,变更则重新加载模块
修改后无需重启服务,下次调用自动生效。
添加新服务器
在 config.json 的 servers 数组中添加条目:
{
"id": "new-server",
"name": "新服务器",
"search": "/10.0.0.100",
"asset_id": "1",
"target_dir": "/opt/app"
}修改 expect 行为
编辑 expect_template.py 的 build_expect_script() 函数,修改后即时生效。
常见问题
Q: 为什么用 expect 而不是 ssh2 库?
JumpServer 堡垒机是交互式菜单程序,不是标准 SSH 跳板机。它禁止 ProxyJump 和端口转发,只能通过模拟键盘输入来操作。expect 是处理这种场景的最可靠方式。
Q: 连接断了怎么办?
使用 ssh_list_sessions 查看会话状态。如果状态是 closed 或 error,重新调用 ssh_connect 即可。
Q: 输出有 ANSI 乱码?
SSH 通过 PTY 传输,会带终端控制字符。这是正常的,命令输出本身不受影响。
Q: 如何调试 expect 脚本?
在 expect_template.py 的关键步骤前添加:
'send_user "DEBUG: 当前步骤\\n"',
"flush stdout",热加载会自动生效。
许可证
MIT
贡献
欢迎提交 Issue 和 Pull Request!
Available Tools
7 toolsssh_closeB
关闭指定的 SSH 会话。
Inputs: session_id (required). Returns: result
ssh_connectC
通过 config.json 配置连接 JumpServer 堡垒机并建立持久 SSH 会话。
Inputs: server_id (required), timeout. Returns: result
ssh_connect_rawB
直接指定参数连接(不依赖 config.json),用于临时连接。
Inputs: host, name, port, user, +8 more. Returns: result
ssh_executeB
在已建立的 SSH 会话中执行命令并返回输出。
Inputs: command (required), session_id (required), timeout. Returns: result
ssh_list_serversA
列出 config.json 中所有可用的服务器配置。
Inputs: no named parameters. Returns: result
ssh_list_sessionsA
列出所有当前活跃的 SSH 会话及其状态。
Inputs: no named parameters. Returns: result
ssh_read_outputA
读取 SSH 会话缓冲区中的最新输出(不发送新命令)。
Inputs: session_id (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a clearly distinct purpose: connecting (two variants), closing, executing, listing servers, listing sessions, and reading output. No overlaps.
All tools follow the pattern 'ssh_<action>' or 'ssh_<verb>_<noun>'. The naming is consistent and predictable.
Seven tools cover the core operations for SSH session management without being excessive or insufficient.
The set includes connection, execution, session listing, and buffer reading. For the intended domain (interactive SSH via JumpServer), no obvious gaps.
Maintenance
Related MCP Connectors
SSH client, server management and one remote MCP URL for your machines, with human approvals.
Secure and manage MCP servers through the Speakeasy AI Control Plane from your agent.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
An MCP server for Arcjet - the runtime security platform that ships with your AI code.
Related MCP Servers
- FlicenseAqualityDmaintenanceA server based on the MCP framework that provides remote server management capabilities through SSH, supporting features like connection pooling, file transfers, and remote command execution.7-
- AlicenseBqualityCmaintenanceA JumpServer 443-only MCP bridge for coding agents that exposes a CLI-first, MFA-compatible, audit-preserving path into JumpServer assets without GUI or port 2222 dependencies.373MIT
- AlicenseNot gradedqualityDmaintenanceSSH-based MCP server that enables remote execution of SSH commands, file transfers, and secure server management via the MCP protocol.ISC
- AlicenseNot gradedqualityCmaintenanceMCP server providing safe, persistent SSH sessions to remote machines with multi-hop ProxyJump tunneling, SFTP file transfer, and stored host profiles.524 npmMIT