使用说明

MCP SSH服务器

LLM代理的远程SSH管理服务器

一个集中式的MCP（模型上下文协议）服务器，使LLM代理（Cursor AI、Claude Desktop、Codex等）能够通过SSH安全地执行命令和管理Linux服务器。

特性

🔐 安全SSH访问 -基于密钥的自动设置身份验证
🌐 官方MCP SDK -流式HTTP(模型上下文协议/python sdk)
🔏 MCP OAuth（RFC 9728） -Claude Code的受保护资源元数据+浏览器登录；与Bearer相同的API令牌
🔄 实时流媒体 -通过SSE进行实时stdout/stderr流式传输
🔑 基于令牌的身份验证 -具有细粒度权限的承载令牌
🛡️ 安全第一 -命令验证、速率限制、审计日志记录
📊 多服务器支持 -从一个端点管理数百台服务器
🚀 生产就绪 -Docker支持、健康检查、优雅关机
🛠️ CLI管理 -通过CLI工具轻松管理服务器/令牌

快速开始

使用Docker（推荐）

# Clone repository
git clone https://github.com/Maxim11111/mcp-ssh.git
cd mcp-ssh

# Copy example configs
cp config/servers.json.example config/servers.json
cp config/tokens.json.example config/tokens.json

# Copy environment configuration
cp env.example .env

# Edit .env file to customize settings (optional)
# nano .env

# Start with Docker Compose
docker-compose up -d

# Quick view servers list
docker exec -it mcp-ssh-server python -m src.cli server list

# Add your first server
docker exec -it mcp-ssh-server python -m src.cli server add

# Check status
docker-compose logs -f mcp-ssh-server

本地安装

# Install dependencies
pip install -r requirements.txt

# Setup configuration
mkdir -p config keys logs
cp config/servers.json.example config/servers.json
cp config/tokens.json.example config/tokens.json

# Add server
python -m src.cli server add

# Start server (factory loads env each process)
uvicorn src.server_http:create_app --factory --host 0.0.0.0 --port 8000

建筑

[Cursor / Claude Code / Codex / …]
         ↓
  HTTPS → Streamable HTTP POST /mcp (Bearer or OAuth access token)
         ↓
  [MCP SSH Server] → SSH Keys → [Your Linux Servers]
         ↓
  Audit Logs + Security Validation

集 PUBLIC_BASE_URL 在 .env 客户端使用的URL（例如。 https://mcp.example.com 在TLS之后）。SDK在以下网址发布OAuth发现 /.well-known/oauth-protected-resource/mcp 以及授权服务器元数据 /.well-known/oauth-authorization-serverMCP OAuth的浏览器登录位于 /login （粘贴您要放入的相同API令牌 Authorization: Bearer).

客户端配置（快速参考）

客户端	配置	注释
光标	`~/.cursor/mcp.json`	`url` + `headers.Authorization: Bearer tok_…`
克劳德代码	`claude mcp add …` 或项目配置	使用以结尾的HTTP传输URL `/mcp`；完成验证令牌来自 `cli token create`，或者如果客户支持，则预先提供承载
OpenAI Codex	`~/.codex/config.toml` 或 `.codex/config.toml`	`[mcp_servers.name]` 随着 `url = "https://host/mcp"` 和 `bearer_token_env_var = "MCP_SSH_TOKEN"` （或 `http_headers`)--看食品法典委员会MCP
谷歌Gemini CLI	`gemini mcp add …`	以结尾的HTTP URL `/mcp`; `-s user` =用户级配置；承载者通过 `--header "Authorization: Bearer tok_…"` 或OAuth `/mcp auth <name>`
工作室	进程环境	`MCP_TOKEN=tok_…` 和 `python -m src.server_stdio`

使用示例

使用Cursor AI

添加 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ssh-devops": {
      "url": "http://your-server:8000/mcp",
      "headers": {
        "Authorization": "Bearer tok_your_token_here"
      }
    }
  }
}

然后在Cursor聊天中：

You: Install nginx on prod-web-01
AI: Executing command on prod-web-01...
✓ nginx installed successfully

使用克劳德桌面

添加 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ssh-devops": {
      "url": "http://your-server:8000/mcp",
      "headers": {
        "Authorization": "Bearer tok_your_token_here"
      }
    }
  }
}

使用克劳德代码（CLI）

在服务器可访问后 PUBLIC_BASE_URL （HTTPS正在生产中）：

claude mcp add --transport http ssh-devops https://your-server.example.com/mcp

使用验证在 /mcp 出现提示时：打开 /login，从粘贴API令牌 python -m src.cli token create。颁发的访问令牌与您的Bearer令牌是相同的字符串。

使用Google Gemini CLI

添加一个可流式传输的HTTP服务器（用户范围配置在 ~/.gemini/):

gemini mcp add devops https://your-server.example.com/mcp --transport http -s user

如果你使用 持有者令牌 在添加服务器时传递它，而不是浏览器OAuth流：

gemini mcp add devops https://your-server.example.com/mcp --transport http -s user \
  --header "Authorization: Bearer tok_your_token_here"

随着 MCP OAuth，先添加服务器，然后在交互式CLI中运行 /mcp auth devops （浏览器重定向到 http://localhost:7777/oauth/callback).

使用OpenAI Codex(`config.toml`)

[mcp_servers.ssh_devops]
url = "https://your-server.example.com/mcp"
bearer_token_env_var = "MCP_SSH_TOKEN"

然后 export MCP_SSH_TOKEN=tok_... 在运行Codex之前。

Stdio（本地）

export MCP_TOKEN=tok_your_token_here
export CONFIG_DIR=./config
python -m src.server_stdio

可用工具

MCP SSH服务器为代理提供以下工具：

execute_命令 -在服务器上执行shell命令
多次执行 -在多台服务器上并行执行命令
read_file -读取文件内容
write_file -写入/更新文件
list_directory -列出目录内容
check_service_status -检查系统服务状态
安装包 -安装软件包（apt/yum/dnf）
list_server -获取可用服务器
get_system_info -获取系统信息

CLI管理

服务器管理

# Add server with automatic SSH key setup
python -m src.cli server add

# List all servers
python -m src.cli server list

# Test connection
python -m src.cli server test prod-web-01

# Remove server
python -m src.cli server remove prod-web-01

许可证管理

# Create new API token
python -m src.cli token create

# List tokens
python -m src.cli token list

# Revoke token
python -m src.cli token revoke tok_abc123

配置

环境变量（.env）

可以使用环境变量配置服务器。复制 env.example 到 .env 并自定义：

# Copy example configuration
cp env.example .env

# Edit configuration
nano .env

关键配置选项：

# Server Configuration
HOST=0.0.0.0                    # Server bind address
PORT=8000                       # Internal container port
EXTERNAL_PORT=8000              # External Docker host port

# Security
TOKEN_EXPIRY_HOURS=8760        # Token validity period

# Rate Limiting
RATE_LIMIT_PER_MINUTE=60       # Requests per minute
RATE_LIMIT_PER_HOUR=500        # Commands per hour

# SSH Settings
SSH_CONNECTION_TIMEOUT=30       # SSH connection timeout
SSH_COMMAND_TIMEOUT=300        # Command execution timeout

反向代理设置

对于使用反向代理（nginx代理管理器、traefik等）的生产部署：

# Use proxy compose file (recommended)
docker-compose -f docker-compose.yml -f docker-compose.proxy.yml up -d

servers.json

{
  "servers": {
    "prod-web-01": {
      "host": "192.168.1.10",
      "port": 22,
      "user": "deploy",
      "ssh_key_path": "/app/keys/prod_web_ed25519",
      "tags": ["production", "web"],
      "enabled": true,
      "description": "Production web server"
    }
  },
  "security": {
    "allowed_commands_patterns": ["^apt ", "^systemctl ", "^docker "],
    "forbidden_commands": ["rm -rf /", "mkfs"],
    "rate_limit": {
      "requests_per_minute": 60,
      "commands_per_hour": 500
    }
  }
}

tokens.json

{
  "tokens": {
    "tok_abc123...": {
      "name": "cursor-admin",
      "permissions": ["execute", "read", "write", "install"],
      "allowed_servers": ["*"],
      "rate_limit_multiplier": 1.0,
      "enabled": true
    }
  }
}

安全

多层安全

持有者代币 -API访问控制
SSH密钥 -服务器身份验证（密钥永远不会离开服务器）
命令验证 -白名单/黑名单模式
速率限制 -每个令牌请求限制
审计日志 -记录所有操作
权限系统 -精细的访问控制

最佳实践

使用ED25519 SSH密钥
定期旋转令牌
配置允许的命令模式
监控审核日志
在生产环境中使用HTTPS（通过nginx代理管理器）
将令牌权限限制为所需的最小值

测试

# Install dev dependencies
pip install -r requirements-dev.txt

# Run tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# View coverage report
open htmlcov/index.html

看测试.md 详细的测试说明。

部署

看部署.md 用于生产部署指南。

文档

QUICKSTART.md -快速启动（RU/EN）
部署.md -生产部署指南
CURSOR_INTEGRATION.md -Cursor AI集成
Developpent.md -开发与调试
MCP_PROTOCOL.md -MCP协议和工具
安全.md -安全最佳实践
测试.md -测试指南

API终点

服务器在单个端点上运行HTTP JSON-RPC（请参见 MCP_PROTOCOL.md):

MCP协议

GET /mcp -服务器信息和可用传输
POST /mcp -JSON-RPC（方法： initialize, tools/list, tools/call)
GET /sse -苏格兰和南方能源公司运输（传统）

效用

GET /health -健康检查

环境变量

所有配置都可以通过以下方式进行管理 .env 文件。看 env.example 对于所有可用选项：

# Server Configuration
HOST=0.0.0.0              # Listen host
PORT=8000                 # Internal container port
EXTERNAL_PORT=8000        # External Docker host port
LOG_LEVEL=INFO            # Logging level

# Directory Configuration
CONFIG_DIR=/app/config    # Configuration directory
KEYS_DIR=/app/keys        # SSH keys directory
LOGS_DIR=/app/logs        # Logs directory

# Security Settings
TOKEN_EXPIRY_HOURS=8760   # Token validity period

# Rate Limiting
RATE_LIMIT_ENABLED=true   # Enable rate limiting
RATE_LIMIT_PER_MINUTE=60  # Requests per minute
RATE_LIMIT_PER_HOUR=500   # Commands per hour

# SSH Settings
SSH_CONNECTION_TIMEOUT=30  # SSH connection timeout
SSH_COMMAND_TIMEOUT=300   # Command execution timeout

# Development Settings
DEBUG=false               # Debug mode
RELOAD=false              # Auto-reload on changes

需求

Python 3.10+
Docker和Docker Compose（用于容器化部署）
SSH访问目标服务器
OpenSSH客户端

贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支
为新功能添加测试
确保所有测试通过
提交拉取请求

许可证

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

支持

GitHub问题：报告错误
文档：请参阅存储库根目录中的*.md文件
电子邮件：your.email@example.com

致谢

建于快速API
MCP协议规范人类
SSH通过参数
SSE流媒体小星星

制作❤️ 面向LLM DevOps社区