ssh-mcp-zlzero 0.1.3

SSH MCP Server (zlzero) - Model Context Protocol server for SSH remote system management

SSH MCP Server

基于 Model Context Protocol (MCP) 的远程 Linux/Unix 服务器管理服务，让 AI 助手通过自然语言即可完成服务器运维、诊断、文件操作等全套任务。

English | 中文

---

目录

• 功能概览
• 应用场景
• 环境要求
• 安装方式
• 配置说明
• MCP 客户端接入
• 工具列表
• 开发指南
• 安全说明
• 免责声明

---

功能概览

功能模块	说明
连接管理	多主机配置、连接测试、自动重连
命令执行	执行单条命令或多行脚本，支持任意 Shell 解释器
系统信息	CPU、内存、磁盘、网络、系统日志一键采集
服务管理	systemd 服务的启停、重启、状态查看
进程管理	进程列表、搜索、终止信号发送
文件操作	读写、追加、列目录、搜索、正则内容匹配
文件传输	SFTP 上传/下载、元信息查询
系统诊断	磁盘健康、高负载分析、网络连通性、安全审计、日志分析

---

应用场景

日常运维

• 一句话查服务器状态：「帮我看一下服务器现在的系统情况」，AI 立即返回 CPU、内存、磁盘、负载汇总。
• 服务快速管理：「重启 nginx」、「查看 mysql 服务状态」、「把 redis 设为开机自启」。
• 批量服务器巡检：配置多台主机，逐一采集系统信息生成巡检报告。

故障排查

• 高负载排查：「服务器 CPU 跑满了，帮我看看是什么进程」，AI 自动分析 top 进程并给出建议。
• OOM 内存溢出排查：查看 dmesg OOM 事件、内存占用最高进程，快速定位问题。
• 磁盘爆满告警：「磁盘快满了」，AI 检查各分区使用率、inode 占用并找出大文件。
• 网络异常诊断：测试出站连通性、DNS 解析、路由表，定位网络层问题。
• 日志快速分析：「分析一下 /var/log/app.log 的错误」，AI 统计 ERROR/WARN/CRITICAL 数量并给出近期错误样本。

安全审计

• 登录异常检测：统计 SSH 暴力破解失败次数，查看近期登录记录。
• 端口安全扫描：列出所有监听端口及关联进程，发现可疑开放端口。
• SUID 文件检查：扫描系统中 SUID 提权文件，识别潜在安全风险。
• 世界可写文件：检查 /tmp、/var/tmp 等目录中的高危权限文件。

文件与配置管理

• 远程配置热改：直接读取并修改 /etc/nginx/nginx.conf、/etc/hosts 等配置文件，无需手动 SSH 登录。
• 日志实时查尾：「看一下 nginx 最近 100 行错误日志」，即时返回结果。
• 配置文件批量下发：将本地修改好的配置文件通过 SFTP 上传到多台服务器。
• 跨服务器文件同步：下载远程文件到本地后，再上传到其他服务器。

自动化脚本执行

• 执行复杂运维脚本：发送多行 Bash/Python 脚本到远程服务器执行，支持任意 Shell 解释器。
• 数据库备份：在远端执行 mysqldump / pg_dump 并将备份文件下载到本地。
• 定时任务检查：查看 crontab 配置，确认定时任务是否正确配置并运行。
• 应用部署辅助：远程 git pull、重建容器、重启服务，完成一键部署流程。

多环境管理

• 开发/测试/生产环境并行管理：通过 SSH_HOSTS_JSON 配置多台服务器，按名称切换，一次会话管理所有环境。
• 容器宿主机管理：查看 Docker/Kubernetes 宿主机的资源使用，辅助容器调度决策。
• 云服务器集群巡检：批量连接 ECS/EC2 实例，汇总各节点状态。

---

环境要求

• Python 3.10+
• uv（推荐）或 pip
• 目标服务器：Linux / Unix（支持 systemd 的发行版效果最佳）

---

安装方式

方式一：uvx 直接运行（无需安装）

uvx ssh-mcp-zlzero --host 192.168.1.100 --username admin --key-file ~/.ssh/id_rsa

方式二：pip 安装

pip install ssh-mcp-zlzero
ssh-mcp-zlzero --host 192.168.1.100 --username admin --key-file ~/.ssh/id_rsa

方式三：源码安装（开发调试）

git clone https://github.com/zhouxiangjing/mcp-ssh.git
cd mcp-ssh
uv pip install -e ".[dev]"

---

配置说明

环境变量

变量名	默认值	说明
SSH_HOST	127.0.0.1	远程主机 IP 或域名
SSH_PORT	22	SSH 端口
SSH_USERNAME	root	SSH 用户名
SSH_PASSWORD	—	密码（使用密钥认证时可省略）
SSH_KEY_FILE	—	私钥路径，如 ~/.ssh/id_rsa
SSH_KEY_PASSPHRASE	—	加密私钥的口令
SSH_TIMEOUT	30	连接超时秒数
SSH_IGNORE_KNOWN_HOSTS	false	跳过主机密钥校验（生产环境不推荐）
SSH_KNOWN_HOSTS_FILE	~/.ssh/known_hosts	自定义 known_hosts 路径
SSH_HOSTS_JSON	—	多主机 JSON 配置（见下方）
MCP_SSH_LOG_LEVEL	WARNING	日志级别：DEBUG / INFO / WARNING / ERROR

将 .env.example 复制为 .env 并填写配置，服务器启动时会自动加载。

CLI 参数

所有环境变量均可通过 CLI 参数覆盖：

ssh-mcp-zlzero \
  --host 192.168.1.100 \
  --port 22 \
  --username admin \
  --key-file ~/.ssh/id_rsa \
  --timeout 60

运行 ssh-mcp-zlzero --help 查看完整参数列表。

多主机配置

通过 SSH_HOSTS_JSON 管理多台服务器，工具调用时传入 host_name 参数即可切换目标主机，省略时使用默认主机：

export SSH_HOSTS_JSON='[
  {"name": "web",   "host": "10.0.0.1", "port": 22,   "username": "admin", "key_file": "~/.ssh/web_key"},
  {"name": "db",    "host": "10.0.0.2", "port": 22,   "username": "root",  "password": "secret"},
  {"name": "edge",  "host": "10.0.0.3", "port": 2222, "username": "ops",   "key_file": "~/.ssh/edge_key"},
  {"name": "dev",   "host": "10.0.0.4", "port": 22,   "username": "dev",   "key_file": "~/.ssh/id_rsa"},
  {"name": "prod",  "host": "10.0.0.5", "port": 22,   "username": "admin", "key_file": "~/.ssh/prod_key"}
]'

---

MCP 客户端接入

Claude Desktop

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "ssh": {
      "command": "uvx",
      "args": ["ssh-mcp-zlzero"],
      "env": {
        "SSH_HOST": "192.168.1.100",
        "SSH_USERNAME": "admin",
        "SSH_KEY_FILE": "~/.ssh/id_rsa"
      }
    }
  }
}

Cursor / 其他 MCP 客户端

{
  "mcpServers": {
    "ssh": {
      "command": "uvx",
      "args": ["ssh-mcp-zlzero"],
      "env": {
        "SSH_HOST": "your-server-ip",
        "SSH_USERNAME": "your-username",
        "SSH_KEY_FILE": "~/.ssh/id_rsa"
      }
    }
  }
}

DeepV Code

在 ~/.deepv/settings.json 的 mcpServers 中添加：

{
  "ssh": {
    "command": "uvx",
    "args": ["--from", "ssh-mcp-zlzero", "ssh-mcp-zlzero"],
    "env": {
      "SSH_HOST": "your-server-ip",
      "SSH_USERNAME": "your-username",
      "SSH_PASSWORD": "your-password",
      "SSH_IGNORE_KNOWN_HOSTS": "true"
    }
  }
}

多主机示例（生产/测试/开发环境并行）：

{
  "ssh": {
    "command": "uvx",
    "args": ["--from", "ssh-mcp-zlzero", "ssh-mcp-zlzero"],
    "env": {
      "SSH_HOSTS_JSON": "[{\"name\":\"prod\",\"host\":\"10.0.0.1\",\"username\":\"admin\",\"key_file\":\"~/.ssh/prod_key\"},{\"name\":\"dev\",\"host\":\"10.0.0.2\",\"username\":\"dev\",\"key_file\":\"~/.ssh/id_rsa\"}]"
    }
  }
}

---

工具列表

连接管理

工具	说明
test_connection	验证 SSH 连接，返回主机名、当前用户、系统负载
list_configured_hosts	列出 SSH_HOSTS_JSON 中所有已配置的命名主机
close_connection	关闭指定主机的 SSH 连接（下次调用自动重连）
close_all_connections	关闭所有活跃的 SSH 连接

命令执行

工具	说明
execute_command	执行单条 Shell 命令，返回 stdout/stderr 及退出码
execute_script	执行多行脚本，支持 bash、sh、python3 等任意解释器

系统信息

工具	说明
get_system_overview	一键采集主机名、OS、内核、负载、CPU、内存、磁盘、网络接口
get_cpu_info	CPU 实时负载、各核使用率、top CPU 进程
get_memory_info	内存与 Swap 使用详情（free/used/cached/available）
get_disk_info	各分区磁盘使用率、inode 占用、I/O 统计
get_network_info	网络接口详情、路由表、活跃连接列表
get_system_logs	读取 journald / syslog 日志，支持按服务过滤
check_service_status	查看 systemd 服务状态（active/inactive/failed）
manage_service	启动/停止/重启/重载/启用/禁用 systemd 服务

进程管理

工具	参数说明
list_processes	按 CPU / 内存 / PID 排序列出进程，默认显示 20 条
find_process	按名称或关键字搜索进程，返回 PID 及详情
kill_process	向指定 PID 发送信号：TERM（优雅）/ KILL（强制）/ HUP（重载）/ USR1 / USR2 / INT / QUIT
get_open_ports	列出所有 TCP/UDP 监听端口及关联进程

文件操作

工具	说明
read_file	读取远程文件内容，支持 max_lines 限制行数（0 = 不限）
write_file	覆盖写入远程文件，自动创建父目录
append_file	追加内容到远程文件末尾
list_directory	列出远程目录（等价于 ls -lah）
delete_file	删除文件或目录，recursive=true 支持递归删除（禁止删除 /、~、.）
search_files	按文件名模式在目录树中搜索，支持 file / dir / any 类型过滤
grep_file	在远程文件中正则搜索，支持递归、忽略大小写、上下文行数

SFTP 文件传输

工具	说明
upload_file	将本地文件通过 SFTP 上传到远程服务器，返回传输字节数
download_file	将远程文件下载到本地，自动创建本地目录
get_file_info	查询远程文件元信息：大小、权限、UID/GID、修改时间

系统诊断

工具	说明
check_disk_health	检查内核磁盘错误日志、失败的 systemd 单元、inode 超 80% 的分区
check_high_load	分析高负载原因：top CPU/内存进程、OOM 事件记录
check_network_connectivity	从远程服务器出发测试 ping 和 DNS 解析，诊断出站网络问题
check_security	安全审计：SSH 失败登录、监听端口、SUID 文件、高危权限文件、近期登录记录
tail_log	读取日志文件末尾 N 行（默认 50 行）
analyze_log_errors	统计日志中 ERROR / WARN / CRITICAL / Exception 数量，并返回近期错误样本

---

开发指南

环境准备

git clone https://github.com/zhouxiangjing/mcp-ssh.git
cd mcp-ssh
uv pip install -e ".[dev]"

运行测试

pytest tests/ -v

测试覆盖率

pytest tests/ --cov=src --cov-report=term-missing

代码检查与格式化

ruff check src/ tests/
ruff format src/ tests/

项目结构

mcp-ssh/
├── src/
│   ├── common/
│   │   ├── config.py          # 环境变量与多主机配置解析
│   │   ├── connection.py      # SSH 连接池与自动重连
│   │   ├── server.py          # MCP Server 实例
│   │   └── utils.py           # 公共工具函数
│   └── tools/
│       ├── connection_mgmt.py # 连接管理工具
│       ├── diagnostics.py     # 系统诊断工具
│       ├── exec.py            # 命令/脚本执行工具
│       ├── file.py            # 文件操作工具
│       ├── process.py         # 进程管理工具
│       ├── sftp.py            # SFTP 传输工具
│       └── system.py          # 系统信息采集工具
└── tests/                     # 单元测试

---

安全说明

• 优先使用密钥认证，避免在配置中明文存储密码。
• 生产环境禁止开启 SSH_IGNORE_KNOWN_HOSTS=true，防止中间人攻击。
• 所有凭据通过环境变量或 .env 文件读取，不会硬编码在代码中。
• .env 文件已通过 .gitignore 排除在版本控制之外。
• delete_file 拒绝删除 /、~、. 等危险路径。
• kill_process 仅允许发送固定白名单信号：TERM / KILL / HUP / USR1 / USR2 / INT / QUIT。
• manage_service 仅允许执行白名单操作：start / stop / restart / reload / enable / disable。

---

免责声明

请在使用本项目前仔细阅读以下声明。使用本项目即表示您已阅读、理解并同意以下所有条款。

风险告知

本项目（SSH MCP Server）通过 AI 模型驱动的自然语言指令对远程服务器执行真实操作，包括但不限于：

• 执行任意 Shell 命令与脚本
• 读写、删除远程文件及目录
• 启停、重启系统服务
• 终止运行中的进程
• 通过 SFTP 上传/下载文件

上述操作均为不可逆或难以回滚的真实变更，一旦执行无法撤销。

责任限制

本项目作者及贡献者对以下情形概不负责，亦不承担任何直接、间接、附带、特殊或衍生损失：

• AI 模型误解用户意图导致执行了错误命令
• 误删文件、误停服务、误杀进程造成的数据丢失或业务中断
• 错误配置导致服务器权限泄露或安全漏洞
• 在生产环境中未经充分验证直接使用造成的任何后果
• 凭据（密码、私钥）通过不安全渠道泄露引发的安全事故
• 因网络中断、SSH 会话异常导致命令执行状态不确定引发的问题
• 第三方 AI 服务（Claude、GPT 等）产生幻觉或错误推理导致的误操作

推荐安全实践

为将操作风险降至最低，强烈建议遵循以下方案：

1. 最小权限原则

为 MCP 专用的 SSH 账号授予最低必要权限，禁止直接使用 root：

# 创建专用运维账号
useradd -m -s /bin/bash mcp-ops

# 仅允许执行特定命令（通过 sudoers 精细控制）
echo 'mcp-ops ALL=(ALL) NOPASSWD: /bin/systemctl status *, /bin/journalctl *' >> /etc/sudoers.d/mcp-ops
chmod 440 /etc/sudoers.d/mcp-ops

2. 生产环境操作前必须备份

# 操作配置文件前先备份
cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak.$(date +%Y%m%d%H%M%S)

# 重要数据目录快照
tar czf /backup/data-$(date +%Y%m%d).tar.gz /var/data/

3. 环境隔离策略

环境	建议
开发环境	可直接使用，风险可控
测试环境	可使用，建议开启操作日志
预发布环境	只读操作自动执行，写操作需人工二次确认
生产环境	强烈建议只读模式，所有变更操作须人工审批后执行

4. 网络访问控制

# 通过 iptables / firewalld 限制 SSH 来源 IP
firewall-cmd --permanent --add-rich-rule='rule family=ipv4 source address=10.0.0.0/24 service name=ssh accept'
firewall-cmd --permanent --add-rich-rule='rule family=ipv4 service name=ssh drop'
firewall-cmd --reload

5. 操作审计日志

# 开启 SSH 会话完整审计（记录所有执行命令）
# 在 /etc/ssh/sshd_config 中添加：
ForceCommand /usr/bin/script -q -f /var/log/ssh-audit/$(date +%Y%m%d-%H%M%S)-$USER.log

或使用 auditd 记录所有 execve 系统调用：

audit -a always,exit -F arch=b64 -S execve -k mcp-ops-audit

6. 密钥安全管理

• 为 MCP 配置专用 SSH 密钥对，与个人密钥严格隔离
• 私钥设置口令（SSH_KEY_PASSPHRASE），禁止使用无口令裸私钥连接生产服务器
• 定期轮换密钥，离职人员的密钥立即吊销
• 禁止将密钥或密码提交到代码仓库

7. 高危操作二次确认建议

在使用 AI 执行以下操作时，务必在 AI 给出命令后，先阅读确认再批准执行，切勿一键允许：

• 任何包含 rm -rf 的删除操作
• systemctl stop / disable 关键服务
• 修改 /etc/sudoers、/etc/passwd、/etc/ssh/sshd_config 等系统配置
• 涉及防火墙规则变更的命令
• 数据库清空或 truncate 操作

适用场景声明

本项目适合用于：

• 个人开发/测试服务器的日常管理
• 内网受控环境下的运维自动化
• 学习 MCP 协议与 AI 运维工具集成
• 只读监控与信息采集场景

本项目不建议直接用于：

• 无备份机制的生产数据库服务器
• 金融、医疗等对数据完整性有严格要求的系统
• 多人共享且无操作审计的服务器环境

---

License

MIT — 详见 LICENSE。