How do I use mcp-ssh?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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

by xiao-linxin

Overview Schema Related Servers Score Discussions

Python

Local

MCP SSH Server

一个基于 expect + Python MCP 的 SSH 持久连接方案，专为 JumpServer 堡垒机设计。

解决传统 SSH MCP 工具无法通过交互式堡垒机保持长连接的问题。

特性

多堡垒机支持 - 一个配置文件管理多台 JumpServer 和多台目标服务器
持久长连接 - 每个连接对应独立 expect 子进程，长期存活无需反复鉴权
并发执行 - 同时连接多台服务器，各自独立互不干扰
热加载 - 修改配置或模板后无需重启，下次调用自动生效
双认证模式 - 支持 SSH 密钥和密码两种认证方式
快速响应 - 使用 marker 分割技术，命令执行后立即返回输出

Related MCP server: mcp-ssh-multi

架构

┌─────────────────────────────────────────────────────────────┐
│                    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 expect

Ubuntu/Debian:

sudo apt-get install expect

CentOS/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": []
    }
  ]
}

配置说明

字段	类型	说明
`id`	string	唯一标识符
`host`	string	服务器地址
`port`	int	SSH 端口（默认 22）
`user`	string	用户名
`auth_type`	string	认证方式：`key` 或 `password`
`key_path`	string	SSH 私钥路径（`auth_type=key` 时必填）
`password`	string	密码（`auth_type=password` 时必填）
`default`	bool	是否为默认堡垒机
`servers`	array	该堡垒机下的目标服务器列表

服务器配置 (servers[]):

字段	类型	说明
`id`	string	服务器唯一 ID（用于 `ssh_connect`）
`name`	string	服务器名称（描述用）
`search`	string	JumpServer 搜索关键词（如 `/192.168.1.100`）
`asset_id`	string	JumpServer 资产 ID
`target_dir`	string	登录后切换的工作目录

使用方法

作为 MCP 服务

在 Claude Code 或其他 MCP 客户端中配置：

{
  "mcpServers": {
    "ssh": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-ssh", "python", "mcp_ssh_server.py"]
    }
  }
}

MCP 工具列表

工具	说明
`ssh_connect`	通过配置连接服务器（推荐）
`ssh_connect_raw`	直接指定参数连接（临时使用）
`ssh_execute`	在会话中执行命令
`ssh_read_output`	读取会话缓冲区输出
`ssh_close`	关闭会话
`ssh_list_sessions`	列出所有活跃会话
`ssh_list_servers`	列出配置中的所有服务器

使用示例

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！

Install Server

license - permissive license

quality

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/xiao-linxin/mcp-ssh'

If you have feedback or need assistance with the MCP directory API, please join our Discord server