ssh-mcp v4.0

用于在 Linux 主机和网络设备上执行持久化 SSH 操作的 MCP 服务器。

功能特性

• 持久化 SSH 连接，支持自动重连

• 安全凭据存储，通过 Windows 凭据管理器实现

• 网络设备支持：Cisco IOS/IOS-XE/XR、MikroTik、FortiGate、Juniper

• 配置管理：网络设备的备份、恢复、差异对比

• SFTP：上传、下载、列出远程文件

• SSH 隧道：持久化端口转发

• 速率限制：防止设备过载（命令之间最小间隔 100ms）

• 智能连接：使用 ssh_connect(alias='vps') 自动加载已保存的凭据

Related MCP server: SSH MCP Server

快速开始

1. 保存服务器（仅需一次）

ssh_save_server(
    alias='vps',
    host='192.168.10.1',
    username='sassogba',
    password='your-password',
    auto_connect=True  # Auto-connect on startup
)

2. 连接（简单模式）

ssh_connect(alias='vps')  # Loads credentials from servers.json

3. 执行命令

ssh_exec(alias='vps', command='df -h')
ssh_exec_sudo(alias='vps', command='systemctl restart nginx', sudo_password='...')

v4.0 新增内容

智能连接模式

• ssh_connect 现在只需提供别名即可自动加载凭据

• 无需每次都提供主机、用户名、密码

• 修复了 Claude Code 集成问题

关键修复

• 超时处理：现在会抛出 TimeoutError，而不是静默返回不完整的缓冲区

• 速率限制：网络命令之间最小间隔 100ms，防止设备过载

• 消除魔法数字：为 shell 尺寸使用命名常量

文档

• 新增 CLAUDE_CODE_USAGE.md，包含完整的使用示例

• 新增 CLAUDE_CODE_SETUP.md，用于配置说明

• 新增 CHANGELOG.md，包含完整的版本历史

安全模型

servers.json 仅保存非敏感元数据。密钥存储在 Windows 凭据管理器中，目标名称格式如下：

• ssh-mcp:<alias>:password

• ssh-mcp:<alias>:key_passphrase

主机密钥策略

• strict：默认值，拒绝未知主机密钥（生产环境）

• auto_add：接受未知主机密钥（仅限实验室环境）

网络设备

支持的设备类型：

• cisco - Cisco IOS/IOS-XE

• cisco_xr - Cisco IOS-XR

• mikrotik - MikroTik RouterOS

• fortigate - FortiGate FortiOS

• juniper - Juniper JunOS

• generic - Linux/Unix（默认）

示例：Cisco 备份

# Save once
ssh_save_server(
    alias='cisco-core',
    host='10.0.0.1',
    username='admin',
    password='...',
    device_type='cisco',
    auto_connect=True
)

# Connect
ssh_connect(alias='cisco-core')

# Backup config
ssh_backup_config(alias='cisco-core', device_type='cisco')
# Saved to: backups/cisco-core/cisco-core_2026-05-31_14-30-00.txt

# Execute commands
ssh_exec_network(
    alias='cisco-core',
    commands=['show version', 'show ip interface brief'],
    device_type='cisco'
)

# Push config
ssh_push_config(
    alias='cisco-core',
    config='''
interface GigabitEthernet0/1
 description Uplink to Core
 ip address 10.0.1.1 255.255.255.0
 no shutdown
''',
    device_type='cisco',
    save_config=True
)

与 Claude Code 配合使用

详细示例请参阅 CLAUDE_CODE_USAGE.md。

简要说明：

1. Save: ssh_save_server(alias='vps', host='192.168.10.1', username='sassogba', password='...')
2. Connect: ssh_connect(alias='vps')
3. Execute: ssh_exec(alias='vps', command='df -h')

提供 18 个工具

连接管理

• ssh_connect - 建立持久化 SSH 连接（智能模式：只需提供别名）

• ssh_disconnect - 关闭连接和隧道

• ssh_list - 列出活动连接及其状态

持久化配置

• ssh_save_server - 将服务器保存到 servers.json（密钥存储在凭据管理器中）

• ssh_remove_server - 移除已保存的服务器

• ssh_list_servers - 列出所有已保存的服务器

Linux/Unix 执行

• ssh_exec - 执行 shell 命令

• ssh_exec_sudo - 使用 sudo 执行（自动注入密码）

网络设备执行

• ssh_exec_network - 在网络设备上执行命令（处理分页、提示符）

• ssh_push_config - 部署配置块

• ssh_backup_config - 将运行配置备份到本地文件

• ssh_restore_config - 从备份文件恢复配置

• ssh_diff_config - 对比配置（git 风格差异）

SFTP

• ssh_upload - 上传文件到远程服务器

• ssh_download - 从远程服务器下载文件

• ssh_list_remote - 列出远程目录内容

隧道

• ssh_tunnel - 创建持久化 SSH 隧道（端口转发）

• ssh_close_tunnel - 按标签关闭隧道

架构

• SSHPool：线程安全的连接池，支持自动重连

• SSHConnection：每连接状态，使用 RLock 保证线程安全

• ThreadPoolExecutor：为 Paramiko（同步库）提供 async/await 封装

• 速率限制器：命令之间最小间隔 100ms，防止设备过载

• 超时处理：多级超时（单命令、总超时、绝对超时），并正确传播错误

环境要求

paramiko>=3.0.0
mcp>=1.0.0
pywin32>=306

安装方式：

pip install -r requirements.txt

运行测试

python -m pytest tests -v

文档

• CLAUDE_CODE_USAGE.md - Claude Code 使用示例

• CLAUDE_CODE_SETUP.md - 配置指南

• CHANGELOG.md - 版本历史和迁移指南

许可证

MIT