SSH 执行器 - MCP 服务器
一个用于通过SSH在远程服务器上执行命令和管理文件的模型上下文协议（MCP）服务器。该服务器基于FastMCP构建，并可通过流式HTTP传输部署到Cloud Run。
概述
这个MCP服务器提供了以下工具：
- 命令执行在远程服务器上运行Shell命令
- 软件包安装使用 apt、yum、pip、npm 等工具安装软件包。
- 脚本执行远程执行 bash/python 脚本
- 文件传输通过SFTP上传和下载文件
- 系统信息收集系统统计信息、磁盘使用情况、进程列表
该服务器采用FastMCP和Paramiko构建，能够连接到任何可通过SSH访问的机器。
项目结构
mcp_server/
├── __init__.py
├── main.py # FastAPI + FastMCP entry point
├── config.py # Pydantic settings configuration
├── tools/ # MCP tool implementations
│ ├── commands.py # Command execution and script running
│ ├── file_transfer.py # SFTP file upload/download
│ └── system_info.py # System information gathering
└── utils/ # Utility functions
├── ssh_client.py # SSH/Paramiko client helpers
└── logger.py # Logging configuration
tests/ # Test suite
└── test_tools.py先决条件
- Python 3.12及以上版本
- 通过以下任一方式访问目标服务器的SSH：
- 私钥认证（推荐） - 密码认证
设置
1. 克隆并安装
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt2. 配置环境（可选）
# Copy example environment file
cp .env.example .env
# Edit .env with default SSH settings (all optional)
# SSH_DEFAULT_USER=ubuntu
# SSH_DEFAULT_KEY_PATH=/path/to/private/key
# LOG_LEVEL=INFO本地运行
# Start the MCP server
python -m mcp_server.main
# Server runs on http://localhost:8080 with streamable HTTP transport部署到 Cloud Run
# Build and deploy using the provided Dockerfile
gcloud run deploy ssh-executor \
--source . \
--region us-central1 \
--allow-unauthenticated
# Or with default SSH settings
gcloud run deploy ssh-executor \
--source . \
--region us-central1 \
--allow-unauthenticated \
--set-env-vars SSH_DEFAULT_USER=ubuntu,LOG_LEVEL=INFO发展
运行测试
# Run all tests
pytest
# Run with coverage
pytest --cov=mcp_server --cov-report=html代码格式化
# Format code with black
black mcp_server/ tests/
# Lint with ruff
ruff check mcp_server/ tests/
# Type checking with mypy
mypy mcp_server/可用工具
命令执行工具
ssh_execute(host, command, ...)- 在远程主机上执行shell命令ssh_install_package(host, packages, package_manager, ...)- 安装软件包（apt/yum/pip/npm）ssh_run_script(host, script_content, interpreter, ...)- 运行 bash/python 脚本
文件传输工具
ssh_upload_file(host, local_path, remote_path, ...)- 通过SFTP上传文件ssh_download_file(host, remote_path, local_path, ...)- 通过SFTP下载文件ssh_create_directory(host, remote_path, ...)- 创建远程目录
系统信息工具
ssh_get_system_info(host, ...)- 获取全面的系统信息ssh_check_disk_space(host, path, ...)- 检查磁盘使用情况ssh_list_processes(host, ...)- 按内存使用量列出前几个进程
认证
所有工具均支持多种认证方法：
- 私钥 （推荐）：
ssh_execute(
host="192.168.1.100",
command="ls -la",
username="ubuntu",
private_key_path="/path/to/key.pem"
)- 密码：
ssh_execute(
host="192.168.1.100",
command="ls -la",
username="ubuntu",
password="your-password"
)- 环境默认值：
设置 SSH_DEFAULT_USER 并且 SSH_DEFAULT_KEY_PATH 在里面 .env，然后：
ssh_execute(host="192.168.1.100", command="ls -la")安全注意事项
- 私钥永远不要将SSH私钥提交到版本控制系统中
- 密码避免在代码中硬编码密码；使用环境变量或安全的密钥管理方式
- Cloud Run（云运行）对于生产环境部署，请使用 Google Secret Manager 来注入 SSH 密钥
- 网络访问确保 Cloud Run 能够访问您的目标服务器（防火墙规则、VPC 等）
示例工作流
设置开发虚拟机
# 1. Get system info
ssh_get_system_info(host="vm-ip", username="ubuntu", private_key_path="key.pem")
# 2. Install dependencies
ssh_install_package(
host="vm-ip",
packages=["git", "python3-pip", "docker.io"],
package_manager="apt",
username="ubuntu",
private_key_path="key.pem"
)
# 3. Create project directory
ssh_create_directory(
host="vm-ip",
remote_path="/home/ubuntu/projects/myapp",
username="ubuntu",
private_key_path="key.pem"
)
# 4. Upload configuration
ssh_upload_file(
host="vm-ip",
local_path="./config.yaml",
remote_path="/home/ubuntu/projects/myapp/config.yaml",
username="ubuntu",
private_key_path="key.pem"
)
# 5. Run setup script
ssh_run_script(
host="vm-ip",
script_content="""
cd /home/ubuntu/projects/myapp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
""",
interpreter="bash",
username="ubuntu",
private_key_path="key.pem"
)与GCP云编排器的集成
这个SSH执行器与GCP云编排器MCP服务器配合得很好：
- 使用
gcp-cloud-orchestrator创建/启动虚拟机 - 使用
ssh-executor配置和管理这些虚拟机 - 使用
gcp-cloud-orchestrator完成时停止/删除虚拟机
在Claude Desktop/Code中，两台服务器可以同时运行。
许可证
麻省理工学院（MIT）
贡献；做出贡献
欢迎贡献！请提交问题或合并请求。