AI导哈

SSH会话管理服务器

一个基于Model Context Protocol (MCP)的服务器，使AI代理能够通过持久SSH会话在远程服务器上执行命令，无需在远程主机上安装任何软件。

  • by kiyo-e
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 kiyo-e/ssh-mcp-server

使用说明

SSH MCP服务器

一种模型上下文协议（MCP）服务器，使Claude Code和Cursor等AI代理能够通过持久的SSH会话在远程服务器上执行命令。采用Bun和Hono构建，性能高，易于部署。

概述

此MCP服务器为AI驱动的开发工具提供了一个安全、有状态的SSH接口。它在内存中保持持久的SSH连接，允许代理在会话之间执行命令，而不需要在远程主机上安装任何软件。

主要优势：

  • 零安装：远程服务器上不需要代理软件
  • 有意义的会议：跨多个命令维护上下文（例如。， cd 随后 ls)
  • 双重运输：既可以作为HTTP服务，也可以作为基于stdio的命令
  • 缺省巩固安全：基于密钥的身份验证，具有自动会话清理功能

特性

  • 持久SSH会话：技术支持 ssh2 30分钟后自动进行空闲清理
  • 三个简单的工具: ssh_open, ssh_exec，以及 ssh_close 用于完全会话控制
  • 柔性运输：HTTP端点(POST /mcp)或用于基于命令的MCP客户端的stdio
  • 轻便快速：基于Bun运行时和Hono web框架构建
  • 集装箱准备就绪：GitHub容器注册表上提供预构建的Docker镜像

快速开始

使用Docker（推荐）

拉取预构建的图像：

docker pull ghcr.io/kiyo-e/ssh-mcp-server:latest

MCP客户端在stdio模式下运行：

docker run --rm -i ghcr.io/kiyo-e/ssh-mcp-server:latest

使用SSH密钥身份验证：

docker run --rm -i \
  -e SSH_PRIVATE_KEY="$(cat ~/.ssh/id_rsa)" \
  ghcr.io/kiyo-e/ssh-mcp-server:latest

地方发展

安装依赖项：

bun install

启动服务器：

# HTTP mode (default port 3000)
bun run start:http

# STDIO mode for command-based MCP clients
bun run start:stdio

MCP工具

此服务器提供了三种管理SSH会话的工具：

工具 说明 参数
ssh_open 使用基于密码或密钥的身份验证打开新的SSH会话 host, username，可选 port，可选 password
ssh_exec 在现有会话上执行命令 sessionId, command，可选 timeoutMs
ssh_close 关闭活动会话并释放资源 sessionId

工作流示例

// 1. Open a session
const session = await ssh_open({
  host: "example.com",
  username: "deploy",
  port: 22
});

// 2. Execute commands (maintains state)
await ssh_exec({ sessionId: session.id, command: "cd /var/www" });
await ssh_exec({ sessionId: session.id, command: "ls -la" });

// 3. Close when done
await ssh_close({ sessionId: session.id });

配置

克劳德代码

快速设置（使用Docker）：

# Add the MCP server using Claude Code CLI
claude mcp add ssh-mcp docker run --rm -i ghcr.io/kiyo-e/ssh-mcp-server:latest

使用SSH密钥身份验证：

# Add with SSH_PRIVATE_KEY environment variable
claude mcp add ssh-mcp docker run --rm -i -e SSH_PRIVATE_KEY ghcr.io/kiyo-e/ssh-mcp-server:latest \
  --env SSH_PRIVATE_KEY="$(cat ~/.ssh/id_rsa)"

或者手动编辑Claude Code配置文件(~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "ghcr.io/kiyo-e/ssh-mcp-server:latest"
      ]
    }
  }
}

使用SSH密钥（手动配置）：

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "SSH_PRIVATE_KEY",
        "ghcr.io/kiyo-e/ssh-mcp-server:latest"
      ],
      "env": {
        "SSH_PRIVATE_KEY": "$(cat ~/.ssh/id_rsa)"
      }
    }
  }
}

OpenAI Codex

添加到您的Codex MCP配置中：

# Add via command line
codex mcp add ssh-mcp docker run --rm -i ghcr.io/kiyo-e/ssh-mcp-server:latest

使用SSH密钥身份验证：

# Add with SSH_PRIVATE_KEY environment variable
codex mcp add ssh-mcp docker run --rm -i -e SSH_PRIVATE_KEY ghcr.io/kiyo-e/ssh-mcp-server:latest \
  --env SSH_PRIVATE_KEY="$(cat ~/.ssh/id_rsa)"

或手动配置：

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "ghcr.io/kiyo-e/ssh-mcp-server:latest"
      ]
    }
  }
}

使用SSH密钥（手动配置）：

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "SSH_PRIVATE_KEY",
        "ghcr.io/kiyo-e/ssh-mcp-server:latest"
      ],
      "env": {
        "SSH_PRIVATE_KEY": "$(cat ~/.ssh/id_rsa)"
      }
    }
  }
}

对于HTTP传输

{
  "mcpServers": {
    "ssh-mcp": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

环境变量

变量 描述 必填
SSH_PRIVATE_KEY 基于密钥的身份验证的私钥内容 否*
PORT HTTP服务器端口（默认值：3000） 否

*如果不使用密码身份验证，则需要 ssh_open

高级用法

自定义端口配置

# HTTP mode with custom port
PORT=4000 bun run src/index.ts

# Docker with custom port
docker run --rm -p 4000:4000 \
  -e PORT=4000 \
  -e SSH_PRIVATE_KEY="$(cat ~/.ssh/id_rsa)" \
  ghcr.io/kiyo-e/ssh-mcp-server:latest

沙盒环境安装

如果Bun无法写入您的临时目录（在沙盒环境中很常见）：

TMPDIR=$(pwd)/.tmp bun install

从源头构建

# Clone the repository
git clone https://github.com/kiyo-e/ssh-mcp-server.git
cd ssh-mcp-server

# Install dependencies
bun install

# Build Docker image
docker build -t ssh-mcp-server .

最佳实践

  • 会话管理：总是打电话 ssh_close 当立即释放资源时
  • 空闲超时：会话在30分钟不活动后自动过期
  • 有状态的命令：利用持久shell进行多步操作（例如。， cd 然后 ls)
  • 安全：尽可能使用基于密钥的身份验证；避免硬编码密码

需求

  • 运行时：Bun v1.1+（用于当地发展）
  • 容器：Docker（可选但推荐）
  • SSH访问：目标远程主机的有效凭据

链接

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

相关 MCP