SSH MCP Server

基于 Model Context Protocol (MCP) 的 SSH 远程服务器管理工具，为 AI 代理提供标准化的 SSH 运维能力。使用 FastMCP + asyncssh 构建。

English

特性

• 连接管理 — 懒连接、健康检查、自动重连、空闲超时
• 命令执行 — 远程命令、sudo（策略门控）、批量执行
• 文件操作 — SFTP 上传 / 下载 / 读写 / 删除 / 列表 / 元数据
• 部署运维 — 完整部署流程：上传 → 备份 → 放置 → 重启
• 安全设计 — 命令黑名单、路径限制、审计日志、确认门控、主机密钥验证
• 多服务器 — 单一配置文件管理多台服务器

快速开始

1. 安装

方式一：下载预编译二进制（推荐）

前往 Releases 下载对应平台的可执行文件：

平台	文件
macOS Apple Silicon	open-ssh-mcp-darwin-arm64
macOS Intel	open-ssh-mcp-darwin-amd64
Linux x86_64	open-ssh-mcp-linux-amd64
Linux ARM64	open-ssh-mcp-linux-arm64
Windows x64	open-ssh-mcp-windows-amd64.exe

下载后赋予执行权限：

chmod +x open-ssh-mcp-darwin-arm64

方式二：从源码安装

pip install -e .

2. 配置

复制示例配置并编辑：

cp config.example.json config.json

完整配置说明见 配置说明。

3. 在 Qoder 中配置

打开 Qoder → Settings → MCP Servers，添加以下配置：

使用预编译二进制（推荐）：

{
  "mcpServers": {
    "ssh": {
      "command": "/path/to/open-ssh-mcp-darwin-arm64",
      "args": ["--config", "/path/to/config.json"]
    }
  }
}

使用 uv 运行（开发模式）：

{
  "mcpServers": {
    "ssh": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/open-ssh-mcp", "ssh-mcp-server"],
      "env": {
        "SSH_MCP_CONFIG": "/path/to/config.json"
      }
    }
  }
}

将 /path/to/ 替换为实际路径。Windows 用户请使用 .exe 文件路径。

4. 在其他 MCP 客户端中配置

Claude Desktop、Cursor 等客户端配置方式类似，在对应的 MCP 配置文件中添加上述 JSON 即可。

配置说明

配置为 JSON 格式，加载优先级：--config 参数 → SSH_MCP_CONFIG 环境变量 → 当前目录 config.json。

{
  "defaults": {
    "port": 22,
    "username": "deploy",
    "auth_method": "key",
    "private_key_path": "~/.ssh/id_ed25519",
    "known_hosts": "~/.ssh/known_hosts",
    "connect_timeout_sec": 10,
    "command_timeout_sec": 30,
    "keepalive_interval_sec": 30,
    "keepalive_count_max": 3
  },
  "servers": {
    "web-prod-01": {
      "host": "10.0.1.11",
      "description": "生产 Web 服务器"
    }
  },
  "security": {
    "command_blocklist": ["rm -rf /", "mkfs", "shutdown", "reboot"],
    "blocked_paths": ["/etc/shadow", "/etc/sudoers"],
    "max_command_timeout_sec": 300,
    "audit_log_path": "~/.ssh-mcp/audit.jsonl",
    "require_confirmation_for": ["sudo", "systemctl restart", "rm"]
  },
  "pool": {
    "max_connections": 10,
    "idle_timeout_sec": 600,
    "health_check_interval_sec": 60,
    "auto_reconnect": true,
    "max_reconnect_attempts": 3
  }
}

设计要点：

• defaults 消除重复配置，每台服务器可覆盖任意字段
• password_env 引用环境变量名 — 配置文件中不存储明文密码
• 安全策略与服务器定义在同一文件中 — 单一配置源

可用工具

连接管理

工具	说明
ssh_connect	建立 SSH 连接
ssh_disconnect	断开连接
ssh_list_servers	列出所有已配置服务器及连接状态
ssh_status	检查连接健康状态：延迟、主机名、操作系统

命令执行

工具	说明
ssh_exec	执行远程命令
ssh_exec_sudo	以 sudo 执行（策略门控）
ssh_exec_batch	顺序执行多条命令

文件操作

工具	说明
ssh_upload	上传本地文件到远程
ssh_download	下载远程文件
ssh_read_file	读取远程文件内容
ssh_write_file	写入 / 追加远程文件
ssh_delete_file	删除远程文件 / 目录
ssh_list_dir	列出目录内容
ssh_stat	获取文件元数据

部署运维

工具	说明
ssh_deploy	完整部署：上传 → 备份 → 放置 → 重启
ssh_restart_service	重启 systemd 服务
ssh_service_status	查看 systemd 服务状态
ssh_service_logs	获取近期服务日志

安全机制

• 命令黑名单 — 硬拒绝危险命令
• 路径限制 — 阻止访问敏感路径
• Sudo 门控 — 特权操作需确认
• 审计日志 — 每次工具调用记录到 JSONL（时间戳、工具、服务器、命令、结果、耗时）
• 主机密钥验证 — 默认通过 known_hosts 启用

开发

# 安装开发依赖
pip install -e '.[dev]'

# 运行测试
pytest

# 代码检查
ruff check src/

# 本地打包（需要 PyInstaller）
pyinstaller --onefile --name open-ssh-mcp --paths src \
  --collect-all pydantic_core --collect-all cryptography \
  --collect-all asyncssh --collect-all mcp \
  build_entry.py

许可证

MIT