SSH Command Executor MCP Server

A secure MCP (Model Context Protocol) server that enables AI assistants to execute commands on remote servers via SSH. Cross-platform support for Windows, macOS, and Linux.

Features

• Secure SSH execution - Execute commands on remote servers with encrypted config storage
• Multiple transport protocols - Support for both stdio and HTTP/WebSocket protocols
• Connection management - Persistent connections with pooling and health checks
• Cross-platform - Works from any OS to any SSH-enabled server
• Security-first - Command validation, audit logging, and access controls
• Easy integration - Works with Claude Desktop, Cursor, VS Code, web apps, and other MCP clients

Quick Start

Installation

git clone <repository-url>
cd ssh-command-executor-mcp
uv sync  # or: pip install -r requirements.txt

Requirements: Python 3.10+

Running the Server

Stdio Transport (for MCP clients like Claude Desktop): ```bash

Using uv (recommended)

uv run -- python run_server.py

Or using Python directly

python run_server.py ```

HTTP Transport (for web applications and direct API access): ```bash

Start HTTP server on localhost:8000

python run_http_server.py

Or with custom host/port

SSH_MCP_HTTP_HOST=0.0.0.0 SSH_MCP_HTTP_PORT=9000 python run_http_server.py ```

Integration

Claude Desktop

Add to your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ssh-command-executor": {
      "command": "uv",
      "args": ["run", "--", "python", "/path/to/ssh-command-executor-mcp/run_server.py"]
    }
  }
}

Replace /path/to/ssh-command-executor-mcp with the actual absolute path to your project directory.

Other MCP Clients

For Cursor, VS Code, or other MCP-compatible tools, configure them to run: ```bash

Using uv (recommended)

uv run -- python /path/to/ssh-command-executor-mcp/run_server.py

Or using Python directly

python /path/to/ssh-command-executor-mcp/run_server.py ```

Replace /path/to/ssh-command-executor-mcp with the actual absolute path to your project directory.

Web Applications & Direct API Access

HTTP REST API: ```bash

Start the HTTP server

python run_http_server.py

Available endpoints:

GET /health - Health check

GET /tools - List available tools

POST /tools/{name} - Execute a tool

GET /prompts - List available prompts

POST /prompts/{name} - Execute a prompt

**WebSocket (Real-time):**

const ws = new WebSocket('ws://localhost:8000/ws');

// Execute a tool ws.send(JSON.stringify({ type: 'tool_call', tool: 'ssh_execute', arguments: { host: '192.168.1.100', username: 'admin', command: 'df -h' } }));

// Handle response ws.onmessage = (event) => { const response = JSON.parse(event.data); console.log('Result:', response.result); }; ```

Usage

Method 1: Configure Once, Use Repeatedly (Recommended)

Configure a server: ``json { "name": "ssh_configure", "arguments": { "name": "production", "host": "prod-server.com", "username": "deploy", "key_path": "~/.ssh/deploy_key" } } ``

Execute commands: ``json { "name": "ssh_run", "arguments": { "command": "systemctl status nginx" } } ``

Method 2: Full Configuration Per Command

{
  "name": "ssh_execute",
  "arguments": {
    "host": "192.168.1.100",
    "username": "admin",
    "command": "df -h",
    "key_path": "/path/to/key"
  }
}

Available Tools

| Tool | Description | Stdio | HTTP | WebSocket | |------|-------------|:-----:|:----:|:---------:| | ssh_configure | Configure server connection details for reuse | ✅ | ✅ | ✅ | | ssh_run | Execute commands on pre-configured servers | ✅ | ✅ | ✅ | | ssh_execute | Execute commands with full connection details | ✅ | ✅ | ✅ | | ssh_test_connection | Test SSH connectivity | ✅ | ✅ | ✅ | | ssh_list_servers | List configured servers | ✅ | ✅ | ✅ |

Available Resources

| Resource | Description | Content Type | |----------|-------------|:------------:| | ssh://servers | List all configured SSH servers | 📋 Server Inventory | | ssh://history | Recent SSH command execution history | 📈 Command History | | ssh://servers/{name}/status | Real-time status of specific server | 📊 Server Status | | ssh://config/security | Current security configuration | 🔒 Security Settings | | ssh://troubleshooting | SSH troubleshooting guide | 📚 Help Documentation |

HTTP API Examples

Execute a command: ``bash curl -X POST http://localhost:8000/tools/ssh_execute \ -H "Content-Type: application/json" \ -d '{ "arguments": { "host": "192.168.1.100", "username": "admin", "command": "df -h", "key_path": "/path/to/key" } }' ``

Test connection: ``bash curl -X POST http://localhost:8000/tools/ssh_test_connection \ -H "Content-Type: application/json" \ -d '{ "arguments": { "host": "server.example.com", "username": "user" } }' ``

Resource Access Examples

View server inventory: ```bash

Via HTTP

curl http://localhost:8000/resources/ssh://servers

MCP clients can access: ssh://servers

**Check command history:**

Via HTTP

curl http://localhost:8000/resources/ssh://history

MCP clients can access: ssh://history

**Get server status:**

Via HTTP

curl http://localhost:8000/resources/ssh://servers/production/status

MCP clients can access: ssh://servers/production/status

## Security Features

- **🔐 Encrypted Storage** - Server configs encrypted with Fernet (AES-128)
- **🛡️ Access Controls** - Host/user validation, SSH key verification
- **🚨 Command Security** - Injection prevention, dangerous command blocking
- **📋 Audit Logging** - Complete operation trail with timestamps

### Security Configuration

Environment variables for enhanced security

export SSH_MCP_ALLOWED_HOSTS="prod.com,staging.com" export SSH_MCP_BLOCKED_COMMANDS="rm -rf,shutdown,reboot" export SSH_MCP_AUDIT_LOG=true

Transport configuration

export SSH_MCP_TRANSPORT=stdio # or 'http' export SSH_MCP_HTTP_HOST=0.0.0.0 # HTTP server host export SSH_MCP_HTTP_PORT=8000 # HTTP server port ```

Project Structure

├── src/
│   ├── server.py          # Main MCP server
│   ├── transport.py       # Transport layer (stdio/HTTP/WebSocket)
│   ├── ssh_tool.py        # SSH execution logic
│   ├── config.py          # Configuration management
│   ├── security.py        # Security controls
│   └── audit.py           # Audit logging
├── tests/                 # Test suite
├── scripts/dev.py         # Development utilities
├── run_server.py          # Stdio transport runner
├── run_http_server.py     # HTTP transport runner
└── requirements.txt       # Dependencies

Development

# Install dependencies
uv sync

# Run tests
uv run pytest

# Format code
uv run black src/ tests/
uv run isort src/ tests/

# Type checking
uv run mypy src/

AI Assistant Usage

With MCP Clients (Claude Desktop, Cursor, etc.)

Once integrated, ask your AI assistant:

• "Execute df -h on my production server to check disk space"
• "Test SSH connection to staging server"
• "Run system updates on my Ubuntu servers"
• "Deploy my application using the deployment script"

With HTTP API

Use the REST API or WebSocket for web applications: ```bash

Check server health

curl http://localhost:8000/health

List available tools

curl http://localhost:8000/tools

Execute SSH command

curl -X POST http://localhost:8000/tools/ssh_execute \ -H "Content-Type: application/json" \ -d '{"arguments": {"host": "server.com", "username": "user", "command": "uptime"}}' ```

Best Practices

• Use SSH keys instead of passwords
• Configure allowed hosts to restrict access
• Use service accounts with minimal permissions
• Enable audit logging for monitoring
• Keep dependencies updated for security

⚠️ Warning: Commands execute with SSH user permissions. Use appropriate access controls.

License

MIT License - see LICENSE file for details.