SSH MCP Server (ssh-mcp)

SSH MCP Server 是一个专为 AI Agent（Claude Code、Cursor、Pi、Windsurf 等）生产运维场景设计的 Profile 驱动型 SSH Model Context Protocol (MCP) 服务端。

相比传统的“单机裸参数 SSH 工具”，本项目围绕多机机房管理、防串台安全护栏、低上下文开销与长连接稳定性进行了深度架构重构，让 AI 在管理数十台生产机、算力机、中转机与 NAS 时既快又稳。

核心特性

1. 防串台双保险（Anti-Drift Target Guard & Target Stamp）

• 显式目标门禁（profileId Guard）：exec 与 sudo-exec 支持传入 profileId 进行目标锁定校验。若当前会话激活机器与传入的 profileId 不一致（例如长任务重连、profiles-reload 重置或并发穿插），服务端立即拒绝执行并报错拦截，彻底杜绝“命令打错机器”。

• 强制首行目标盖章（Target Stamp）：每一次命令返回（含成功与非零退出）首行固定输出：

  [ssh-mcp] target id=prod-main name="生产主节点" host=198.51.100.10:22

  且在配置层严格禁止 id / name / host 含换行符，防止输出伪造。

2. 分桶目录按需检索（Bucketed Catalog）

• 告别全量倾倒：profiles-list 仅返回当前会话目标（sessionActiveProfile）、磁盘默认目标（fileActiveProfile）与分桶目录计数（如 生产端、显卡机、中转、客户服务器），不把几十台机器详情一次性塞进上下文。

• 多维精准检索：通过 profiles-find 按分桶（bucket）或中英文关键词（query，匹配 id / name / aliases / host / user / note / tags）按需展开机器卡片。

3. 连接保活与通道防泄漏（Resilient SSH Lifecycle）

• SSH KeepAlive & 断线即刻感知：内置连接池复用与心跳保活，底层 Socket 异常断流时立即中止挂起等待，不傻等超时。

• 迟到通道自动回收（Late-Channel Cleanup）：命令超时触发 SIGTERM 并销毁连接后，若远端迟到返回 Channel 流，自动执行关闭回收，绝不误杀后续新建连接。

• 输出截断保护（Output Truncation）：内置 maxOutputChars 保护，防止远端巨量日志打爆 Agent 上下文。

4. 安全凭据与原子化持久化（Zero-Leak & Atomic Persistence）

• 密钥零回显：支持 ${ENV_VAR} 环境变量占位符展开；任何列表、检索与报错均自动脱敏密码与私钥正文。

• 按需私钥校验：启动与改配置时不因某台冷备机的私钥路径缺席而阻断全局服务，仅在实际连接或 profiles-test 时校验目标机密钥。

• 原子写盘 + 两阶段删机：配置更新采用同目录临时文件 + rename 原子替换；删除机器强制经过 profiles-delete-prepare（自动备份 + 生成校验口令）与 profiles-delete-confirm 两步确认。

Related MCP server: fast-mcp-ssh

工具列表（MCP Tools）

快速上手

1. 安装与构建

git clone https://github.com/KonglingDaDa/ssh-mcp.git
cd ssh-mcp
npm install
npm run build

2. 编写配置文件（ssh-mcp.profiles.yaml）

参考 examples/ssh-mcp.profiles.yaml：

version: 1
activeProfile: prod-main

defaults:
  timeout: 120000
  maxChars: none
  disableSudo: false

buckets:
  - id: production
    name: 生产端
    aliases: [生产, prod, production]
    note: 核心线上机器
  - id: gpu
    name: 算力机
    aliases: [显卡, gpu-cluster, gpu]

profiles:
  - id: prod-main
    name: 生产主节点
    aliases: [主站, US-Prod]
    host: 198.51.100.10
    port: 22
    user: root
    auth:
      type: key
      keyPath: ./keys/prod-main.pem
    note: "核心业务容器宿主机，部署目录 /root/app-prod"
    tags: [production, us]

3. 接入 MCP 客户端

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "node",
      "args": [
        "/path/to/ssh-mcp/build/index.js",
        "--config=/path/to/ssh-mcp.profiles.yaml"
      ]
    }
  }
}

可选启动参数：

• --config=<path>（必填）：YAML/JSON 配置文件路径

• --profile=<id>（可选）：锁定启动默认激活的机器 ID

• --timeout=<ms>（可选）：默认命令超时时间（毫秒，默认 60000）

• --maxChars=<number|none>（可选）：命令长度上限（默认 1000，设为 none 不限）

• --disableSudo（可选）：彻底隐藏并禁用 sudo-exec 工具

推荐的 Agent 运维工作流

1. 先查目标，不盲打：调用 profiles-list 查看 sessionActiveProfile 与分桶目录。

2. 按桶或关键词找机器：调用 profiles-find({ bucket: "生产" }) 或 profiles-find({ query: "198.51.100.10" }) 获取准确 id。

3. 显式切机 + 连通性预检：需换机器时调用 profiles-use({ profileId })，关键操作前调用 profiles-test({ profileId })。

4. 带 profileId 防串台执行：调用 exec({ profileId: "prod-main", command: "hostname && whoami && hostname -I", description: "核对生产主节点身份" })，并核对返回首行 [ssh-mcp] target 盖章。

开发与测试

# 离线快速单测（不依赖 Docker / 127.0.0.1:2222）
npm test

# 本地 SSH 容器集成测试（先 docker compose up -d）
npm run test:docker

# Testcontainers 冒烟测试
npm run test:smoke

# 编译 TypeScript
npm run build

项目目录结构

• src/config/：profile 配置加载与校验

• src/profile/：会话目标、持久化与分桶目录（profile-manager.ts、profile-catalog.ts）

• src/ssh/：SSH 连接、保活、断流监听、迟到通道回收

• src/tools/：MCP 工具（exec / sudo-exec / profiles-*，目标门禁与输出截断在 result.ts）

• docs/INTENT.md：架构意图与契约

• skills/ssh-mcp-operator/：Agent 操作技能

• examples/ssh-mcp.profiles.yaml：示例配置（*.example.com 与环境变量占位）

• test/：Vitest 单测、集成测试与夹具

License

MIT © KonglingDaDa