Skip to main content
Glama
BingZi-233

ssh-mcp

by BingZi-233
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

ssh-mcp

面向多服务器运维的 SSH / SFTP CLI 与 MCP 服务。

用一份可审计的服务器配置，完成远程命令、文件传输、端口转发和基础健康检查。

npm Node.js GitHub stars License LINUX DO

ssh-mcp 把日常 SSH 操作收敛成一个可脚本化的命令行工具，也可以作为 MCP stdio 服务接入 Claude Code、Codex 等客户端。它不替代服务器权限系统：连接使用现有 SSH 凭据，命令仍在目标服务器上执行，安全拦截只作为额外保护层。

当前版本：1.5.2 · Node.js 18+ · MIT

安装 · 5 分钟上手 · 配置 · 命令参考 · MCP 接入

核心能力

能力

说明

远程执行

单台或批量执行命令，保留 stdout、stderr 和退出码

文件传输

SFTP 后台任务、进度轮询、取消和断点续传

网络通道

本地转发和远程转发，访问内网 HTTP 或 TCP 服务

运行检查

健康检查、证书信息、环境信息、远程 HTTP 请求

配置运维

服务器间直传、配置对比、目录快照、脚本执行

AI 接入

MCP stdio 服务和 Claude/Codex 插件清单

Related MCP server: vps-mcp

适合什么场景

  • 日常登录多台服务器，快速执行命令并保留清晰的退出码和输出。

  • 上传或下载大文件，任务在后台运行并支持断点续传。

  • 从跳板机访问内网 HTTP 服务或数据库端口。

  • 让 MCP 客户端在明确的服务器配置和安全策略下执行运维动作。

安装

npm install -g @bingzi-233/ssh-mcp
ssh-mcp --help

从源码安装：

git clone https://github.com/BingZi-233/ssh-mcp.git
cd ssh-mcp
npm ci
npm run build
npm link

5 分钟上手

cp servers.example.json servers.json
$EDITOR servers.json

ssh-mcp list-servers
ssh-mcp run-command -s prod-web -c "hostname && uptime"
ssh-mcp health -s prod-web

如果配置文件不在当前目录：

SSH_MCP_CONFIG=~/.config/ssh-mcp/servers.json ssh-mcp list-servers

配置服务器

默认读取当前工作目录的 servers.json，也可以用 SSH_MCP_CONFIG 指定路径。配置每次调用都会重新读取，修改后不需要重启进程。

{
  "security": {
    "blocked_patterns": ["shutdown\\s+-h", "reboot"]
  },
  "servers": [
    {
      "name": "prod-web",
      "description": "生产 Web",
      "host": "192.168.1.10",
      "port": 22,
      "username": "deploy",
      "privateKeyPath": "~/.ssh/id_ed25519"
    },
    {
      "name": "staging",
      "host": "staging.example.com",
      "username": "deploy",
      "password": "仅供本地测试使用"
    }
  ]
}

复制示例配置：

cp servers.example.json servers.json
export SSH_MCP_CONFIG="$PWD/servers.json"

认证优先级为：私钥 → 密码 → SSH_AUTH_SOCK 中的 ssh-agent。不要把真实密码或私钥提交到 Git；servers.json 默认已被 .gitignore 排除。

CLI 快速开始

ssh-mcp list-servers
ssh-mcp run-command -s prod-web -c "hostname && uptime"
ssh-mcp batch --servers prod-web,staging -c "df -h /"
ssh-mcp health -s prod-web

每个命令都有独立帮助：

ssh-mcp <命令> --help

命令总览

命令

用途

list-servers

列出配置的服务器

run-command

执行远程 shell 命令

batch

并发执行批量命令

open-session / close-session / list-sessions

管理可复用 SSH 长连接

upload / download

SFTP 后台传输与断点续传

transfer-status / cancel-transfer

查看或取消传输任务

forward / list-forwards / close-forward

本地或远程 SSH 端口转发

ls / stat / rm / mkdir

SFTP 浏览和文件操作

health

OS、磁盘、内存、负载和 CPU 检查

cert-info

检查远程 SSL/TLS 证书

copy-between

两台远程服务器之间直传

diff-servers

对比两台服务器的同一路径

exec-script

上传、执行并清理脚本

snapshot

将远程目录打包下载为 tar.gz

tail-f / stop-tail / list-tails

轮询追踪远程文件

watch / stop-watch / list-watches

定时执行命令并显示变化

curl

从远程网络环境发起 HTTP 请求

env

收集远程环境信息

常用操作

长连接会话

长连接只复用 TCP 和认证；每条命令仍在独立 channel 中执行，不会保留 cd 或环境变量。

ssh-mcp open-session -s prod-web
# 从输出中取得 s1
ssh-mcp run-command -s prod-web --session s1 -c "hostname"
ssh-mcp close-session -i s1

文件传输与续传

目标文件已有部分内容时，默认从目标大小处继续；使用 --overwrite 从头开始。

ssh-mcp upload -s prod-web -l ./release.tar.gz -r /tmp/
ssh-mcp transfer-status
ssh-mcp download -s prod-web -r /var/log/app.log -l ./logs/ --overwrite
ssh-mcp cancel-transfer -i t1

端口转发

# 本机 8080 → SSH 服务器 → 内网 192.168.1.5:80
ssh-mcp forward -s prod-web -L 8080:192.168.1.5:80

# SSH 服务器 9000 → 本机 localhost:3000
ssh-mcp forward -s prod-web -R 9000:127.0.0.1:3000

ssh-mcp list-forwards
ssh-mcp close-forward -i f1

服务器间直传和配置对比

ssh-mcp copy-between --src web1 --dst web2 \
  --src-path /opt/app/config.yml --dst-path /opt/app/config.yml

ssh-mcp diff-servers --server-a web1 --server-b web2 \
  --path /etc/nginx/nginx.conf

安全策略

run-command 默认拦截以下高危模式：

  • rm -rf /、rm -rf /* 等根目录递归删除

  • dd 覆盖块设备

  • mkfs.* 在块设备上创建文件系统

  • 重定向覆盖块设备

  • fork bomb

可以在 security.blocked_patterns 中追加正则。--force 会跳过内置和自定义检查，只应在确认目标和命令后使用。安全策略是最后一道保护，仍应使用最小权限账号、SSH key 和服务器侧审计。

MCP 模式

以 stdio MCP 服务启动：

npx -y @bingzi-233/ssh-mcp --mcp

Claude Code：

claude mcp add ssh -- npx -y @bingzi-233/ssh-mcp --mcp

本仓库也包含 Claude/Codex 插件清单：

/plugin marketplace add BingZi-233/ssh-mcp
/plugin install ssh-mcp@bingzi-plugins

codex plugin marketplace add BingZi-233/ssh-mcp
codex plugin add ssh-mcp@bingzi-plugins

Codex 插件目录位于 plugins/ssh-mcp，其中的 .codex-plugin/plugin.json、.mcp.json 和 skills/ 与 Claude 插件配置共用同一套 npm MCP 服务。

MCP 客户端启动前，请确保工作目录中存在 servers.json，或在客户端配置中设置 SSH_MCP_CONFIG。可用工具会从配置文件动态读取服务器列表。

开发与验证

npm ci
npm run build
npm audit --omit=dev
npm run dev

发布流程：推送 v* 标签后，GitHub Actions 会构建并发布 npm 包。发布前请确认版本号、CHANGELOG、npm run build 和安全审计均通过。

排障

找不到服务器配置

确认当前目录有 servers.json，或检查：

echo "$SSH_MCP_CONFIG"
ssh-mcp --help

认证失败

确认 username、私钥路径和私钥口令；私钥支持 ~ 展开。也可以先运行 ssh -v 验证系统 SSH 凭据。

传输没有结束

传输是后台任务，使用 transfer-status 查看状态。若目标文件大小超过源文件，使用 --overwrite 重新开始。

MCP 客户端看不到工具

确认启动参数包含 --mcp，配置文件路径可读，并从客户端日志检查 stdio 进程是否正常启动。

许可证

MIT © BingZi-233

社区

本项目由 LINUX DO 社区孵化并认可。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcpHydroSSH

    hydroCoderClaud
    A
    license
    A
    quality
    C
    maintenance
    An SSH MCP server that enables users to connect to and manage remote servers directly from Claude Code. It provides tools to execute commands, monitor connection status, and dynamically manage server configurations through natural language.
    10
    121 npm
    6
    MIT

  • vps-mcp

    ereskovsky
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server for managing VPS servers via SSH, enabling command execution, file transfer, Docker management, and server documentation from within Claude.
    13 npm
    ISC

  • mcp-impresario

    Pharbi
    F
    license
    Not graded
    quality
    D
    maintenance
    MCP server for Claude Code to execute commands on any remote server over SSH. Provides tools for remote execution, file operations, and connection info.
    1
    -