MCP SSH Gateway

A Model Context Protocol (MCP) server for managing Linux servers via SSH. This server provides tools for executing commands, managing files, monitoring services, and analyzing logs on remote Linux systems.

Installation

Docker (Recommended)

1. Build and run with Docker Compose:

docker compose up -d

No .env file is required. SSH_HOST and SSH_USER are defined in docker-compose.yml (with defaults), and SSH_KEY_FILE defaults to /app/ssh_keys/id_ed25519.

On first container start, the entrypoint checks for /app/ssh_keys/id_ed25519. If it does not exist, a new ed25519 key pair is generated automatically. The /app/ssh_keys folder is mounted as a Docker volume, so the key persists across restarts.

Manual Installation

1. Install dependencies:

pip install -r requirements.txt

2. Set environment variables:

export SSH_HOST=your-server.example.com
export SSH_USER=root
export SSH_PASSWORD=your_password
# OR
export SSH_KEY_FILE=/path/to/private/key

3. Run the server:

python -m ssh_mcp_server.server

AnythingLLM Integration

Add the following configuration to your anythingllm_mcp_servers.json:

{
  "mcpServers": {
    "mcp-ssh-gateway": {
      "name": "MCP SSH Gateway",
      "type": "streamable",
      "url": "http://mcp-ssh-gateway:8000/mcp",
      "auth_token": null,
      "enabled": true
    }
  }
}

Configuration

Environment Variables

Variable	Description	Default
SSH_HOST	Target server hostname or IP	localhost
SSH_USER	SSH username	root
SSH_PASSWORD	SSH password	-
SSH_KEY_FILE	Path to SSH private key	/app/ssh_keys/id_ed25519
SSH_PORT	SSH port	22
AUTH_TOKEN	Optional bearer token for MCP HTTP auth	-
CLIENT_ID	OAuth client ID for /oauth/token	-
CLIENT_SECRET	OAuth client secret for /oauth/token	-
SERVER_URL	Optional external base URL for OAuth metadata endpoints	-
SERVER_HOST	MCP server bind address	0.0.0.0
SERVER_PORT	MCP server port	8000

Authentication

The server supports two authentication methods:

1. Password Authentication: Set SSH_PASSWORD in your environment
2. Key-based Authentication: By default, Docker uses /app/ssh_keys/id_ed25519 (auto-generated on first run). You can still override SSH_KEY_FILE if needed.

MCP HTTP Authentication (Optional)

Set AUTH_TOKEN to require bearer authentication on all incoming MCP HTTP requests.

• Header required: Authorization: Bearer <AUTH_TOKEN>
• Missing or incorrect token: HTTP 401 Unauthorized
• AUTH_TOKEN unset: authentication is disabled and requests are allowed through

OAuth 2.0 Client Credentials

The server exposes POST /oauth/token for client credentials token exchange.

• Required env vars: CLIENT_ID, CLIENT_SECRET, and AUTH_TOKEN
• Request body (application/json or form-encoded):
  • client_id
  • client_secret
  • optional grant_type=client_credentials
• Success response: bearer token payload with access_token equal to AUTH_TOKEN
• Invalid credentials: HTTP 401 with invalid_client
• Missing server config (CLIENT_ID, CLIENT_SECRET, or AUTH_TOKEN): HTTP 503

Usage

Basic Connection Test

# Test SSH connection
test_ssh_connection(
    hostname="server.example.com",
    username="root",
    password="your_password"
)

Execute Commands

# Execute a simple command
execute_command("ls -la /var/log")

# Execute with sudo
execute_command("systemctl status nginx", use_sudo=True)

File Operations

# Read a file
read_file("/etc/nginx/nginx.conf")

# Write to a file
write_file("/tmp/test.txt", "Hello World!")

# List directory contents
list_directory("/var/log")

Service Management

# Check service status
get_service_status("nginx")

# Start a service
start_service("nginx")

# Stop a service
stop_service("nginx")

# Restart a service
restart_service("nginx")

Process Management

# List all processes
list_processes()

# List specific processes
list_processes(filter_by="nginx")

# Kill a process
kill_process("12345", signal="TERM")

Network Tools

# Check if port is open
check_port(80)

# Get network connections
get_network_connections()

Log Analysis

# Tail a log file
tail_log("/var/log/nginx/access.log", lines=100)

# Search in logs
search_log("/var/log/nginx/error.log", "error")

Security Considerations

• Use SSH key-based authentication when possible
• Limit SSH access to specific users and IPs
• Regularly rotate SSH keys and passwords
• Monitor SSH access logs
• Use sudo judiciously and limit sudo privileges

Troubleshooting

Connection Issues

1. Authentication Failed: Check username, password, or key file
2. Connection Refused: Verify SSH service is running and port is correct
3. Host Key Verification: Ensure the server's host key is trusted

Permission Issues

1. File Access Denied: Check file permissions and ownership
2. Sudo Required: Use use_sudo=True for privileged operations
3. Service Management: Ensure user has appropriate systemd permissions

Performance Issues

1. Slow Commands: Increase timeout values for long-running commands
2. Connection Timeouts: Check network connectivity and server load
3. Resource Usage: Monitor server resources during operations

API Reference

The server exposes the following MCP tools:

• test_ssh_connection: Test SSH connectivity
• get_server_info: Get system information
• execute_command: Execute commands
• read_file: Read file contents
• write_file: Write file contents
• list_directory: List directory contents
• get_service_status: Check service status
• start_service: Start a service
• stop_service: Stop a service
• restart_service: Restart a service
• list_processes: List running processes
• kill_process: Kill a process
• check_port: Check port status
• get_network_connections: Get network connections
• tail_log: Tail log files
• search_log: Search log files

License

This project is licensed under the MIT License.