Skip to main content
Glama
yongxiaodong

ssh-remote-mcp

by yongxiaodong
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

ssh-remote-mcp

一个用于 通过 SSH 安全诊断远程服务器 的 MCP 服务。 让 AI（Claude Code / Codex 等）能去线上机器排查问题——看日志、查 CPU/内存/磁盘、服务、端口、 Docker、Plesk……默认不能做破坏性改动,写操作需要你点确认或显式开启。

两条设计原则

  1. 提供能力,不提供流程：像 Filesystem MCP 那样,只给少量通用、可组合的原语 (run_command / read_file / tail_file / list_dir / list_hosts),命令由 Agent 自己组合, 没有 restart_nginx 这种硬编码流程。

  2. 读自动、写收口：每条命令在任何 SSH 之前先判定——

    • 只读且安全 → 自动执行；

    • 写 / 敏感 / 未知 → 走 run_write_command,需你在客户端点确认后才执行(否则只返回建议命令,绝不静默写)。

    SSH 账号本身的 OS 权限是最终防线,推荐用非 root 的排查账号。

Related MCP server: Simple SSH MCP Server

🚀 快速开始（Docker,推荐）

1. 克隆

git clone https://github.com/yongxiaodong/ssh-remote-mcp.git
cd ssh-remote-mcp

2. 配置要诊断的主机

cp config/hosts.example.yaml config/hosts.docker.yaml
$EDITOR config/hosts.docker.yaml

容器会把你的 ~/.ssh 整个挂到 /keys,所以 key_path 用容器内路径 /keys/<私钥文件名>：

transport: { mode: stdio }            # 容器里实际用 http 启动(见 docker-compose），此处随意
security:
  mode: diagnostic                    # 读自动；写经 run_write_command 确认
  enable_write_tool: true             # 暴露写工具(默认 true)；设 false 则纯只读
hosts:
  my-server:
    host: 1.2.3.4
    port: 22
    user: root                        # 建议用非 root 排查账号
    key_path: /keys/id_rsa            # = ~/.ssh/id_rsa（~/.ssh 已挂到 /keys）
    accept_unknown_hosts: true        # 测试用；生产请挂 known_hosts

3. 启动（监听 127.0.0.1:15555）

docker compose -f docker/docker-compose.yml up -d --build

换机器 / 非 501 用户时,带上你的 uid:gid（让容器能读 0600 权限的私钥）：

SRM_UID=$(id -u) SRM_GID=$(id -g) docker compose -f docker/docker-compose.yml up -d --build

常用管理：

docker compose -f docker/docker-compose.yml logs -f      # 看日志/审计
docker compose -f docker/docker-compose.yml restart      # 改了 config 后重载
docker compose -f docker/docker-compose.yml down         # 停

改了代码/规则表要 up -d --build；只改 config/hosts.docker.yaml 用 restart 即可。

4. 接入 Claude Code

claude mcp add --transport http -s user ssh-remote-mcp http://127.0.0.1:15555/mcp
claude mcp list        # 看到 ✔ Connected

-s user = 所有项目可用。新开一个会话即可看到工具。

5. 接入 Codex

codex mcp add ssh-remote-mcp --url http://127.0.0.1:15555/mcp
codex mcp list

Claude Code 和 Codex 共用同一个 HTTP 端点,只要容器在跑就都能连。

6. 跑一条测试指令

在 Claude Code / Codex 里直接说：

用 ssh-remote-mcp 看一下 my-server 的运行时长和磁盘使用

它会调用 run_command,只读命令自动执行,例如 uptime; df -h：

03:25:34 up 12 days, 10:45,  0 users,  load average: 0.29, 0.09, 0.03
Filesystem      Size  Used Avail Use% Mounted on
/dev/vda2        96G   16G   77G  17% /

试试写操作(如"创建 /tmp/t1"):它会调用 run_write_command,客户端弹出允许/拒绝,你点允许才执行。

工具

工具

作用

list_hosts

列出已配置的主机(绝不泄露密钥)

run_command

执行命令/管道；只读自动跑,写则返回建议

read_file

读取文件(敏感路径需确认,带大小上限)

tail_file

查看文件末尾 N 行,可选关键字过滤

list_dir

列目录

run_write_command

执行写/变更命令,必须经你确认才运行(默认开启)

安全行为速查

  • ✅ 自动执行：只读命令、只读管道/串接(| ; && ||)、只读分组子shell ( … )、 无害重定向(2>/dev/null、2>&1)、变量赋值 f=/path; … $f。

  • 🔒 需确认 / 拦截：写文件(> file)、rm/mv/chmod/systemctl restart/docker run 等变更、 读敏感文件(key//etc/shadow/.env…)、命令替换 $(…)/反引号、进程替换 <(…)、后台 &、 以及 awk/sed/php/mysql 等可写/可执行代码的双刃命令。

  • 输出会做密钥/密码脱敏,每条命令都写审计日志(不记原始敏感输出)。

判定逻辑是纯函数、无 I/O,"危险命令在连服务器之前就被拦下"由测试保证 (tests/unit/test_engine.py)。

配置

详见 config/hosts.example.yaml 和 docs/configuration.md。 要新增放行命令而不重建镜像,写进 security.ruleset_extra 后 restart 即可。

本地开发(不用 Docker)

需要 Python 3.11+：

python3.12 -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"

cp config/hosts.example.yaml config/hosts.yaml      # 编辑主机(key_path 用本机 ~/.ssh 路径)
ssh-remote-mcp --transport stdio                    # 或 --transport http --port 15555

测试：

pytest tests/unit                                   # 离线,始终安全
SSH_REMOTE_MCP_IT=1 IT_SSH_HOST=1.2.3.4 IT_SSH_KEY=~/.ssh/id_rsa \
  pytest tests/integration -m integration           # 打真机,仅只读

License

MIT

This server cannot be installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

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

Latest Blog Posts

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/yongxiaodong/ssh-remote-mcp'

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