AI导哈

SSH远程命令执行服务器

一个最小化的MCP服务器，通过SSH在远程主机上执行命令并检查输出，支持Claude Code和OpenAI Codex等MCP兼容AI使用。

  • by plmi
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 plmi/ssh-mcp

使用说明

SSH MCP服务器

一个暴露一个工具的最小MCP服务器-- ssh_exec --因此，Claude Code、OpenAI Codex或任何兼容MCP的AI都可以通过SSH在远程主机上运行命令并检查输出。它支持两者 stdio 和 streamable-http 运输。

它做什么

  • 默认情况下启动MCP stdio服务器。
  • 也可以通过以下方式为MCP服务 streamable-http 在 /mcp.
  • 暴露 ssh_exec(command, host, user, password, port, identity_file, timeout_sec, strict_host_key_checking).
  • 用途 参数 对于SSH--不依赖于系统 ssh 二元的。
  • 支持 密码认证 和 公钥认证.
  • 返回结构化输出： ok, exit_code, stdout, stderr, target.

先决条件

  • 码头工人
  • 克劳德代码CLI(claude)和/或OpenAI Codex CLI(codex)已安装并验证

塑造形象

cd /path/to/ssh-mcp
docker build -t ssh-mcp:latest .

以流式HTTP运行

集 MCP_TRANSPORT=streamable-http 启动HTTP MCP端点，而不是默认的stdio服务器。

本地Python

python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt

MCP_TRANSPORT=streamable-http \
MCP_HOST=127.0.0.1 \
MCP_PORT=8000 \
python server.py

MCP端点将在 http://127.0.0.1:8000/mcp.

码头工人

在Docker中运行时，绑定到 0.0.0.0 因此，该端口可以在集装箱外到达：

docker run --rm -p 8000:8000 \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8000 \
  -e SSH_DEFAULT_HOST=your-host.example.com \
  -e SSH_DEFAULT_USER=ubuntu \
  -e SSH_ALLOWED_HOSTS=your-host.example.com \
  ssh-mcp:latest

MCP端点将在 http://localhost:8000/mcp.

如果您的客户端支持无状态HTTP MCP会话，请添加 -e MCP_STATELESS_HTTP=true 到 docker run 命令。

添加到克劳德代码

选项1:Claude Code CLI（推荐）

这些示例使用默认值 stdio 运输。

基于密钥的身份验证：

claude mcp add sshRemote -- \
  docker run --rm -i \
  -v "$HOME/.ssh:/home/app/.ssh:ro" \
  -e HOME=/home/app \
  -e SSH_DEFAULT_HOST=your-host.example.com \
  -e SSH_DEFAULT_USER=ubuntu \
  -e SSH_ALLOWED_HOSTS=your-host.example.com \
  ssh-mcp:latest

密码验证：

claude mcp add sshRemote -- \
  docker run --rm -i \
  -e SSH_DEFAULT_HOST=your-host.example.com \
  -e SSH_DEFAULT_USER=ubuntu \
  -e SSH_DEFAULT_PASSWORD=your-password \
  -e SSH_ALLOWED_HOSTS=your-host.example.com \
  ssh-mcp:latest

验证是否已添加：

claude mcp list

选项2： ~/.claude.json （手动配置）

将以下内容添加到您的 ~/.claude.json 在...之下 mcpServers 按键：

{
  "mcpServers": {
    "sshRemote": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/Users/<your-user>/.ssh:/home/app/.ssh:ro",
        "-e", "HOME=/home/app",
        "-e", "SSH_DEFAULT_HOST=your-host.example.com",
        "-e", "SSH_DEFAULT_USER=ubuntu",
        "-e", "SSH_ALLOWED_HOSTS=your-host.example.com",
        "ssh-mcp:latest"
      ]
    }
  }
}

选项3：项目级配置(.claude/settings.json)

要将服务器范围限定到单个项目，请将其添加到 .claude/settings.json 在项目根目录中：

{
  "mcpServers": {
    "sshRemote": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/Users/<your-user>/.ssh:/home/app/.ssh:ro",
        "-e", "HOME=/home/app",
        "-e", "SSH_DEFAULT_HOST=your-host.example.com",
        "-e", "SSH_DEFAULT_USER=ubuntu",
        "-e", "SSH_ALLOWED_HOSTS=your-host.example.com",
        "ssh-mcp:latest"
      ]
    }
  }
}

添加到OpenAI Codex

选项1：Codex CLI（推荐）

这些示例使用默认值 stdio 运输。

codex mcp add sshRemote -- \
  docker run --rm -i \
  -v $HOME/.ssh:/home/app/.ssh:ro \
  -e HOME=/home/app \
  -e SSH_DEFAULT_HOST=your-host.example.com \
  -e SSH_DEFAULT_USER=ubuntu \
  -e SSH_ALLOWED_HOSTS=your-host.example.com \
  ssh-mcp:latest

codex mcp list

选项2： ~/.codex/config.toml

[mcp_servers.sshRemote]
command = "docker"
args = [
  "run", "--rm", "-i",
  "-v", "/Users/<your-user>/.ssh:/home/app/.ssh:ro",
  "-e", "HOME=/home/app",
  "-e", "SSH_DEFAULT_HOST=your-host.example.com",
  "-e", "SSH_DEFAULT_USER=ubuntu",
  "-e", "SSH_ALLOWED_HOSTS=your-host.example.com",
  "ssh-mcp:latest"
]
startup_timeout_sec = 20
tool_timeout_sec = 120

然后重新启动Codex（CLI/TUI/IDE扩展）并验证：

codex mcp list

指定主机、用户和端口

您有两种方法可以提供连接详细信息：

通过环境变量（每次调用的默认值）

通过 -e 旗帜到 docker run:

变量 示例 描述
SSH_DEFAULT_HOST my-server.example.com 远程主机名或IP
SSH_DEFAULT_USER ubuntu SSH登录用户名
SSH_DEFAULT_PORT 2222 SSH端口（默认： 22)
SSH_ALLOWED_HOSTS my-server.example.com 以逗号分隔的主机列表

通过工具参数（每次调用覆盖）

您还可以在提示AI时直接传递连接详细信息：

Run ssh_exec with host="10.0.1.50", user="admin", port=2222, command="uptime"

每次调用的参数会覆盖环境变量的默认值。

认证

这 ssh_exec 工具根据您提供的内容选择身份验证方法：

您提供的内容 使用的验证方法
password 仅密码身份验证（禁用密钥查找）
identity_file 指定的私钥文件
两者都不是 密钥来自 ~/.ssh SSH代理自动尝试

密码认证

将密码作为环境变量默认值或每次调用参数传递：

默认情况下（env-var）：

-e SSH_DEFAULT_PASSWORD=hunter2

作为每次通话的参数：

Run ssh_exec with host="10.0.1.50", user="admin", password="hunter2", command="uptime"

提供密码后，密钥查找和SSH代理将被禁用，因此身份验证方法是明确的。

公钥认证

安装您的 ~/.ssh 将目录放入容器中，服务器将自动尝试在那里找到的密钥（如果转发套接字，则包括SSH代理）：

-v "$HOME/.ssh:/home/app/.ssh:ro"
-e HOME=/home/app

使用特定密钥文件而不是扫描 ~/.ssh，将其作为每次调用参数传递：

Run ssh_exec with host="10.0.1.50", user="admin", identity_file="/home/app/.ssh/id_deploy", command="uptime"

设置（如果您还没有密钥对）：

  1. 生成密钥：

    ssh-keygen -t ed25519 -C "ssh-mcp"

  2. 将其复制到远程主机：

    ssh-copy-id -i ~/.ssh/id_ed25519.pub user@your-host.example.com

  3. 测试无密码登录：

    ssh user@your-host.example.com "echo ok"

环境变量引用

变量 默认值 描述
SSH_DEFAULT_HOST （无） 默认远程主机
SSH_DEFAULT_USER （无） 默认SSH用户名
SSH_DEFAULT_PASSWORD （无） 默认SSH密码（密码认证）
SSH_DEFAULT_PORT 22 默认SSH端口
SSH_DEFAULT_TIMEOUT_SEC 60 默认命令超时（秒）
SSH_CONNECT_TIMEOUT_SEC 10 SSH连接超时（秒）
SSH_ALLOWED_HOSTS （无，允许所有） 逗号分隔的主机列表
SSH_MAX_OUTPUT_CHARS 12000 输出截断限制
MCP_TRANSPORT stdio MCP传输： stdio 或 streamable-http
MCP_HOST 127.0.0.1 为HTTP传输绑定主机
MCP_PORT 8000 绑定HTTP传输端口
MCP_STREAMABLE_HTTP_PATH /mcp MCP端点的HTTP路径
MCP_STATELESS_HTTP false 启用无状态流式HTTP会话
MCP_MOUNT_PATH / 高级：FastMCP使用的ASGI安装路径

示例提示

  • “使用 sshRemote ssh_exec 然后跑 uname -a."
  • “跑 df -h 在远程主机上，总结磁盘使用情况。"
  • “跑 journalctl -u nginx -n 200 --no-pager 并查找最近的错误。"
  • “检查CPU负载 my-server.example.com 和 uptime."

安全说明

  • 此服务器可以执行任意远程shell命令——将其视为高权限工具。
  • 始终设置 SSH_ALLOWED_HOSTS 以限制可以针对哪些主机。
  • 尽可能在远程主机上使用权限最低的SSH用户。
  • 保持 strict_host_key_checking=true （默认）以防止MITM攻击。
  • 在可能的情况下，更喜欢基于密钥的身份验证而不是密码。如果您确实使用了密码，请通过环境变量传递它，而不是作为工具参数传递，这样它就不会出现在对话日志中。

相关 MCP