tonton2006/ssh-executor-mcp

SSH Executor - MCP Server

A Model Context Protocol (MCP) server for executing commands and managing files on remote servers via SSH. Built with FastMCP and deployable to Cloud Run with streamable HTTP transport.

Overview

This MCP server provides tools for:

• Command Execution: Run shell commands on remote servers
• Package Installation: Install packages using apt, yum, pip, npm, etc.
• Script Execution: Execute bash/python scripts remotely
• File Transfer: Upload and download files via SFTP
• System Information: Gather system stats, disk usage, process lists

Built with FastMCP and Paramiko, this server can connect to any SSH-accessible machine.

Project Structure

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

Prerequisites

• Python 3.12+
• SSH access to target servers with either:
  • Private key authentication (recommended)
  • Password authentication

Setup

1. Clone and Install

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2. Configure Environment (Optional)

# 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

Running Locally

# Start the MCP server
python -m mcp_server.main

# Server runs on http://localhost:8080 with streamable HTTP transport

Deploying to 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

Development

Running Tests

# Run all tests
pytest

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

Code Formatting

# Format code with black
black mcp_server/ tests/

# Lint with ruff
ruff check mcp_server/ tests/

# Type checking with mypy
mypy mcp_server/

Available Tools

Command Execution Tools

• ssh_execute(host, command, ...) - Execute a shell command on remote host
• ssh_install_package(host, packages, package_manager, ...) - Install packages (apt/yum/pip/npm)
• ssh_run_script(host, script_content, interpreter, ...) - Run bash/python scripts

File Transfer Tools

• ssh_upload_file(host, local_path, remote_path, ...) - Upload file via SFTP
• ssh_download_file(host, remote_path, local_path, ...) - Download file via SFTP
• ssh_create_directory(host, remote_path, ...) - Create remote directory

System Information Tools

• ssh_get_system_info(host, ...) - Get comprehensive system information
• ssh_check_disk_space(host, path, ...) - Check disk usage
• ssh_list_processes(host, ...) - List top processes by memory usage

Authentication

All tools support multiple authentication methods:

1. Private Key (Recommended):

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

2. Password:

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

3. Environment Defaults: Set SSH_DEFAULT_USER and SSH_DEFAULT_KEY_PATH in .env, then:

   ssh_execute(host="192.168.1.100", command="ls -la")
   

Security Notes

• Private Keys: Never commit SSH private keys to version control
• Passwords: Avoid hardcoding passwords; use environment variables or secure secret management
• Cloud Run: For production deployments, use Google Secret Manager to inject SSH keys
• Network Access: Ensure Cloud Run can reach your target servers (firewall rules, VPC, etc.)

Example Workflows

Setting Up a Development VM

# 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"
)

Integration with GCP Cloud Orchestrator

This SSH Executor pairs well with the GCP Cloud Orchestrator MCP server:

1. Use gcp-cloud-orchestrator to create/start VMs
2. Use ssh-executor to configure and manage those VMs
3. Use gcp-cloud-orchestrator to stop/delete VMs when done

Both servers can run simultaneously in Claude Desktop/Code.

License

MIT

Contributing

Contributions welcome! Please open an issue or submit a pull request.