AI导哈

SSH服务器管理工具

一个用于可信内网测试环境的SSH MCP服务器，支持动态注册服务器、执行远程命令、传输文件及交互式排障。

  • by ReduckProject
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 ReduckProject/ssh-server-mcp

使用说明

SSH Server MCP

一个面向可信内网测试环境的 SSH MCP（Model Context Protocol）服务器，用于动态管理测试服务器连接、执行命令、传输文件和开展交互式排障。

项目定位与使用边界

本项目定位为可信内网测试环境中的高权限排障工具，不面向公网或生产环境。它假设 MCP 客户端、运行本程序的本地主机以及目标测试服务器均处于受信任边界内。

为提高测试排障效率，本项目有意采用以下设计：

  • 允许通过 MCP 动态注册测试服务器，无需修改配置或重启服务
  • 允许执行任意远程命令，便于定位临时、复杂和交互式问题
  • 允许在本地与测试服务器之间传输文件和目录
  • 支持长生命周期的交互式 SSH 会话

这些能力是针对受控测试环境的便利性取舍，不提供生产级的命令白名单、远程主机准入、操作审批或强制主机密钥验证。请勿将本项目暴露到公网、接入生产服务器，或在多人不可信环境中共享使用。

功能特性

  • 动态注册SSH服务器 - 快速接入临时测试服务器，支持密码和私钥两种认证方式
  • 配置文件加载 - 通过 --config 参数预加载服务器配置
  • 执行远程命令 - 在已注册的服务器上执行任意命令
  • 有界命令输出 - stdout 和 stderr 默认各保留最新 1 MiB，可通过 maxBytes 调整
  • 流式文件传输 - 基于本地路径上传和下载时使用流式复制，避免大文件整体载入内存
  • 连接管理 - 自动重连、连接测试
  • 安全隐藏 - 列出服务器时自动隐藏密码

安装构建

.\build.ps1

启动方式

1. MCP服务器模式（默认）

./ssh-server-mcp.exe --config=servers.csv

2. 交互式Shell模式

./ssh-server-mcp.exe --shell --config=servers.csv

交互式Shell提供类似XShell的体验：

╔════════════════════════════════════════════╗
║       SSH Server MCP - Interactive Shell   ║
╚════════════════════════════════════════════╝

输入 'help' 查看可用命令, 'exit' 退出

ssh-mcp> list
┌──────┬─────────────────────┬──────┬──────────┬─────────┐
│ 名称 │ 地址                │ 端口 │ 用户     │ 状态    │
├──────┼─────────────────────┼──────┼──────────┼─────────┤
│ prod │ 43.167.188.85       │ 22   │ root     │ 离线    │
└──────┴─────────────────────┴──────┴──────────┴─────────┘

ssh-mcp> connect prod
已连接到 prod (root@43.167.188.85:22)

prod> uname -a
Linux VM-0-7-opencloudos 6.6.117-45.1.oc9.x86_64 ...

prod> shell
# 进入真正的SSH终端模式

prod> exit
再见!

交互式命令：

命令 说明
list, ls 列出所有服务器
connect <name> 连接服务器
disconnect 断开当前连接
exec <cmd> 执行命令
shell 进入终端模式
add <name> <host> <port> <user> <pass> 添加服务器
remove <name> 移除服务器
info [name] 显示服务器信息
help 显示帮助
exit 退出

连接服务器后可直接输入命令执行。

配置文件格式

支持CSV和JSON两种格式，根据文件扩展名自动识别。

CSV格式（推荐，易于编辑）

# SSH服务器配置文件
# 格式: name,host,port,user,password,keyFile
# password和keyFile二选一，不需要的字段留空
# 密码含逗号时用双引号包裹

prod-server,192.168.1.100,22,root,your-password,
dev-server,dev.example.com,22,admin,"pass,word",
key-server,10.0.0.1,2222,ubuntu,,~/.ssh/id_rsa
列 说明
name 服务器名称（唯一标识）
host 服务器地址
port SSH端口（默认22）
user 用户名
password 密码（含逗号需用引号包裹）
keyFile 私钥文件路径

私钥路径和文件传输的本地路径支持 ~、$VAR、${VAR} 和 %VAR% 环境变量，并会转换为规范化的绝对路径。

JSON格式

{
  "servers": [
    {
      "name": "prod-server",
      "host": "192.168.1.100",
      "port": 22,
      "user": "root",
      "password": "your-password"
    },
    {
      "name": "dev-server",
      "host": "dev.example.com",
      "user": "admin",
      "keyFile": "~/.ssh/id_rsa"
    }
  ]
}

提供的工具

1. register_ssh_server

注册一个新的SSH服务器连接。

参数:

参数 类型 必需 描述
name string 是 服务器名称，用于后续引用
host string 是 服务器地址
port number 否 SSH端口，默认22
user string 是 用户名
password string 否* 密码（与keyFile二选一）
keyFile string 否* 私钥文件路径（与password二选一）

*密码和私钥必须提供其中之一

2. unregister_ssh_server

注销一个已注册的SSH服务器。

参数:

参数 类型 必需 描述
name string 是 要注销的服务器名称

3. list_ssh_servers

列出所有已注册的SSH服务器。

4. ssh_execute

在指定的SSH服务器上执行命令。

参数:

参数 类型 必需 描述
server string 是 服务器名称
command string 是 要执行的命令
timeout number 否 超时时间（秒），默认30秒
maxBytes number 否 stdout 和 stderr 各自保留的最大字节数，默认 1048576，最大 10485760；超限时保留最新输出

5. 异步命令任务

用于启动长时间运行的非交互命令，MCP 调用无需等待命令结束。stdout 和 stderr 分开增量读取，每个任务都有独立超时和有界缓冲。

工具 说明
ssh_command_start 启动异步命令，返回 taskId 和初始输出
ssh_command_read 读取尚未消费的 stdout/stderr
ssh_command_status 查询状态但不消费输出
ssh_command_cancel 取消运行中的命令并返回已有输出
ssh_command_list 列出运行中及最近完成的任务

默认任务超时为 300 秒，最大 3600 秒；stdout 和 stderr 默认各使用 1 MiB 缓冲。全局最多同时运行 16 个任务，每台服务器最多 4 个。完成的任务保留 10 分钟，便于读取最终输出。

6. test_ssh_connection

测试指定SSH服务器的连接状态。

参数:

参数 类型 必需 描述
name string 是 服务器名称

安装配置

构建

.\build.ps1

在Claude Desktop中配置

编辑Claude Desktop配置文件（Windows: %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "ssh-server": {
      "command": "E:\\Code\\GitHub\\ssh-server-mcp\\ssh-server-mcp.exe",
      "args": ["--config=E:\\Code\\GitHub\\ssh-server-mcp\\servers.csv"]
    }
  }
}

在Claude Code中配置

编辑 ~/.claude/settings.json 或使用 /update-config 命令：

{
  "mcpServers": {
    "ssh-server": {
      "command": "E:\\Code\\GitHub\\ssh-server-mcp\\ssh-server-mcp.exe",
      "args": ["--config=E:\\Code\\GitHub\\ssh-server-mcp\\servers.csv"]
    }
  }
}

使用示例

注册服务器（密码认证）

{
  "name": "register_ssh_server",
  "arguments": {
    "name": "my-server",
    "host": "192.168.1.100",
    "port": 22,
    "user": "admin",
    "password": "your-password"
  }
}

注册服务器（私钥认证）

{
  "name": "register_ssh_server",
  "arguments": {
    "name": "prod-server",
    "host": "production.example.com",
    "user": "deploy",
    "keyFile": "C:\\Users\\YourName\\.ssh\\id_rsa"
  }
}

执行命令

{
  "name": "ssh_execute",
  "arguments": {
    "server": "my-server",
    "command": "ls -la /var/log",
    "timeout": 60
  }
}

列出服务器

{
  "name": "list_ssh_servers",
  "arguments": {}
}

测试连接

{
  "name": "test_ssh_connection",
  "arguments": {
    "name": "my-server"
  }
}

注销服务器

{
  "name": "unregister_ssh_server",
  "arguments": {
    "name": "my-server"
  }
}

安全注意事项

本项目的安全边界是可信内网测试环境。使用时请遵守以下约束：

  1. 仅限测试环境 - 不要连接生产服务器，不要将 MCP 服务暴露到公网
  2. 可信客户端 - 仅允许受信任的本地 MCP 客户端调用本服务
  3. 高权限能力 - 动态注册、任意命令执行和文件传输均为预期功能，调用方拥有与 SSH 账号等同的权限
  4. 密码存储 - 当前版本密码存储在进程内存中，服务器重启后需要重新注册；配置文件和凭证文件不得提交到版本库
  5. 主机密钥 - 当前接受所有主机密钥，以方便临时测试服务器接入；不要在不可信网络中使用
  6. 最小化凭证 - 建议使用专用测试账号和测试密钥，不要复用生产环境凭证

技术架构

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   MCP Client    │────▶│   MCP Server     │────▶│  SSH Servers    │
│  (Claude/etc)   │     │  (this project)  │     │  (remote)       │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌──────────────────┐
                        │ Server Manager   │
                        │ - Register       │
                        │ - Unregister     │
                        │ - Execute        │
                        │ - List           │
                        └──────────────────┘

许可证

MIT License

相关 MCP