Ssh Executor MCP

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.txt

2. 配置环境（可选）

# 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, ...) - 按内存使用量列出前几个进程

认证

所有工具均支持多种认证方法：

1. 私钥 （推荐）：

   ssh_execute(
       host="192.168.1.100",
       command="ls -la",
       username="ubuntu",
       private_key_path="/path/to/key.pem"
   )

1. 密码：

   ssh_execute(
       host="192.168.1.100",
       command="ls -la",
       username="ubuntu",
       password="your-password"
   )

1. 环境默认值：

设置 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服务器配合得很好：

1. 使用 gcp-cloud-orchestrator 创建/启动虚拟机
2. 使用 ssh-executor 配置和管理这些虚拟机
3. 使用 gcp-cloud-orchestrator 完成时停止/删除虚拟机

在Claude Desktop/Code中，两台服务器可以同时运行。

许可证

麻省理工学院（MIT）

贡献；做出贡献

欢迎贡献！请提交问题或合并请求。