ssh-mcp

一个基于 Model Context Protocol (MCP) 的 SSH 工具服务，支持：

• 同时面向 1 到多台 Linux 服务器 执行命令
• 同一次调用里，对不同主机执行 不同操作
• 每个操作使用独立执行上下文，避免 stdout/stderr、退出码、超时结果互相污染
• 支持两种目标来源：
  • 本地别名配置（config/targets.json）
  • 临时 inline 目标（调用时直接传 host/username/...）

当前支持的 MCP tools

• ssh_exec
• ssh_target_list
• ssh_connection_close

1. 安装

环境要求

• Node.js 18+
• 可访问目标 Linux 主机的 SSH 网络
• 目标主机已开启 SSH 服务

安装依赖

npm install

构建

npm run build

启动 MCP Server

node dist/index.js

这是一个 stdio MCP server，正常情况下不直接面向人类交互，而是由 Claude Desktop / Cursor 等 MCP 客户端拉起。

2. 目标配置

默认会从下面路径读取服务器别名配置：

config/targets.json

也可以通过环境变量覆盖：

SSH_MCP_TARGETS_FILE=/absolute/path/to/targets.json

配置示例

{
  "targets": {
    "web1": {
      "host": "10.0.0.11",
      "username": "deploy",
      "useAgent": true,
      "hostKeySha256": "SHA256:REPLACE_WITH_REAL_FINGERPRINT"
    },
    "db1": {
      "host": "10.0.0.21",
      "port": 22,
      "username": "postgres",
      "privateKeyPath": "C:/Users/me/.ssh/id_ed25519",
      "hostKeySha256": "SHA256:REPLACE_WITH_REAL_FINGERPRINT"
    }
  }
}

认证方式

当前支持：

• useAgent: true
• privateKeyPath
• auth: { "type": "password", "password": "..." }

说明：

• 推荐优先使用 SSH agent 或 privateKeyPath
• password 模式虽然支持，但不推荐长期使用，因为某些 MCP 客户端会记录工具调用参数
• hostKeySha256 必填，必须以 SHA256: 开头

3. 在 MCP 客户端中配置

Claude Desktop / Cursor 风格配置示例

把下面内容加入 MCP 配置：

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "node",
      "args": [
        "E:/tmp/multi-mcp/dist/index.js"
      ]
    }
  }
}

如果你想指定别名配置文件路径：

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "node",
      "args": [
        "E:/tmp/multi-mcp/dist/index.js"
      ],
      "env": {
        "SSH_MCP_TARGETS_FILE": "E:/tmp/multi-mcp/config/targets.json"
      }
    }
  }
}

4. Tool 用法

4.1 ssh_target_list

列出当前配置文件里的别名目标。

输入： 无

返回示例：

[
  {
    "alias": "db1",
    "host": "10.0.0.21",
    "port": 22,
    "username": "postgres",
    "authMode": "privateKeyPath"
  },
  {
    "alias": "web1",
    "host": "10.0.0.11",
    "port": 22,
    "username": "deploy",
    "authMode": "agent"
  }
]

4.2 ssh_exec

执行一个或多个 SSH 操作。每个 operation 都可以使用不同的目标和不同的命令。

用别名执行

{
  "operations": [
    {
      "operationId": "check-web",
      "target": { "alias": "web1" },
      "command": "hostname && uptime"
    }
  ]
}

同一次调用，多个主机执行不同命令

{
  "operations": [
    {
      "operationId": "web-status",
      "target": { "alias": "web1" },
      "command": "systemctl status nginx --no-pager"
    },
    {
      "operationId": "db-load",
      "target": { "alias": "db1" },
      "command": "uptime"
    }
  ],
  "maxConcurrency": 2,
  "defaultTimeoutMs": 10000
}

用 inline 目标执行

{
  "operations": [
    {
      "operationId": "inline-check",
      "target": {
        "host": "10.0.0.99",
        "username": "root",
        "useAgent": true,
        "hostKeySha256": "SHA256:REPLACE_WITH_REAL_FINGERPRINT"
      },
      "command": "echo hello"
    }
  ]
}

支持字段

每个 operation 支持：

• operationId
• target
• command
• cwd
• env
• stdin
• timeoutMs
• pty

返回结果是按输入顺序排列的 JSON 文本，包含：

• ok
• exitCode
• signal
• stdout
• stderr
• stdoutBytes
• stderrBytes
• stdoutTruncated
• stderrTruncated
• timedOut
• cancelled
• durationMs
• errorCode
• errorMessage

4.3 ssh_connection_close

关闭当前进程里缓存的 SSH 连接。

关闭全部连接

{}

关闭指定连接

{
  "connectionKeys": ["web1", "[email protected]:22"]
}

说明：

• 如果目标来自 alias，连接 key 通常就是 alias，例如 web1
• 如果目标来自 inline，连接 key 通常是 username@host:port

5. 安全注意事项

• 默认要求 hostKeySha256，避免无校验直连
• 建议使用 SSH agent 或私钥路径
• 不建议在生产里长期用 password auth
• stdout/stderr 有大小上限，过长输出会被截断并标记 stdoutTruncated/stderrTruncated

6. 当前限制

当前版本 不支持：

• SCP / SFTP
• 跳板机 / ProxyJump
• 交互式 shell 会话
• 长时间流式输出推送

当前版本聚焦于：

• 多主机命令执行
• 隔离结果聚合
• 别名与临时目标混用