mcp-ssh by Maxim11111 - MCP Server

MCP SSH Server

Remote SSH Management Server for LLM Agents

A centralized MCP (Model Context Protocol) server that enables LLM agents (Cursor AI, Claude Desktop, Codex, etc.) to securely execute commands and manage Linux servers via SSH.

Features

🔐 Secure SSH Access - Key-based authentication with automatic setup
🌐 Network Architecture - HTTP/SSE transport for remote agent connectivity
🔄 Real-time Streaming - Live stdout/stderr streaming via SSE
🔑 Token-based Auth - Bearer tokens with granular permissions
🛡️ Security First - Command validation, rate limiting, audit logging
📊 Multi-server Support - Manage hundreds of servers from one endpoint
🚀 Production Ready - Docker support, health checks, graceful shutdown
🛠️ CLI Management - Easy server/token management via CLI tool

Quick Start

Using Docker (Recommended)

# 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

# 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

Local Installation

# 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
python -m src.server

Architecture

[Cursor/Claude/Codex Agent]
         ↓
  HTTPS/SSE (Bearer Token)
         ↓
  [MCP SSH Server] → SSH Keys → [Your Linux Servers]
         ↓
  Audit Logs + Security Validation

Usage Examples

With Cursor AI

Add to ~/.cursor/mcp.json:

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

Then in Cursor chat:

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

With Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Available Tools

MCP SSH Server provides these tools to agents:

execute_command - Execute shell command on a server
execute_on_multiple - Execute command on multiple servers in parallel
read_file - Read file contents
write_file - Write/update files
list_directory - List directory contents
check_service_status - Check systemd service status
install_package - Install packages (apt/yum/dnf)
list_servers - Get available servers
get_system_info - Get system information

CLI Management

Server Management

# 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

Token Management

# 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

Configuration

Environment Variables (.env)

The server can be configured using environment variables. Copy env.example to .env and customize:

# Copy example configuration
cp env.example .env

# Edit configuration
nano .env

Key configuration options:

# 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

Reverse Proxy Setup

For production deployments with reverse proxy (nginx-proxy-manager, traefik, etc.):

# 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
    }
  }
}

Security

Multi-layer Security

Bearer Tokens - API access control
SSH Keys - Server authentication (keys never leave server)
Command Validation - Whitelist/blacklist patterns
Rate Limiting - Per-token request limits
Audit Logging - All operations logged
Permission System - Granular access control

Best Practices

Use ED25519 SSH keys
Rotate tokens regularly
Configure allowed command patterns
Monitor audit logs
Use HTTPS in production (via nginx-proxy-manager)
Limit token permissions to minimum required

Testing

# 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

See for detailed testing instructions.

Deployment

See for production deployment guide.

Documentation

- Production deployment guide
- Cursor AI integration
- Security best practices
- Testing guide

API Endpoints

MCP Protocol Endpoints

POST /mcp/v1/initialize - Initialize MCP session
POST /mcp/v1/tools/list - List available tools
POST /mcp/v1/tools/call - Execute tool
POST /mcp/v1/command/stream - Create streaming session
GET /mcp/v1/sse/{session_id} - SSE streaming endpoint

Utility Endpoints

GET /health - Health check
GET /api/servers - List servers (debug)

Environment Variables

All configuration can be managed via .env file. See env.example for all available options:

# 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

Requirements

Python 3.10+
Docker & Docker Compose (for containerized deployment)
SSH access to target servers
OpenSSH client

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Add tests for new features
Ensure all tests pass
Submit a pull request

License

MIT License - see file for details.

Support

GitHub Issues: Report bugs
Documentation: See docs folder
Email: your.email@example.com

Acknowledgments

Built with FastAPI
MCP Protocol specification by Anthropic
SSH via Paramiko
SSE streaming via sse-starlette

Made with ❤️ for the LLM DevOps community