MCP VPS Manager

MCP VPS Manager is a secure, production-ready Model Context Protocol (MCP) server that enables Large Language Models to safely manage Virtual Private Servers via SSH. This tool provides comprehensive VPS management capabilities with built-in security controls, connection pooling, and comprehensive audit logging.

Features

Core Functionality

• SSH Command Execution: Execute shell commands with security validation and real-time streaming

• Command Queuing: Priority-based command queuing with rate limiting and concurrency control

• File Operations: Upload, download, read, and write files via SFTP

• System Monitoring: Real-time system metrics (CPU, memory, disk, processes)

• Service Management: Control systemd, upstart, and SysV init services with container-aware detection

• Multi-Server Support: Manage multiple VPS servers from a single interface

Security Features

• Command Validation: Blocks dangerous commands (rm -rf /, fork bombs, etc.)

• Path Restrictions: Restricts file access to configured allowed paths

• SSH Key Authentication: Only supports SSH key-based authentication

• Sudo Password Management: Secure in-memory sudo password handling

• Audit Logging: Comprehensive logging of all operations

Performance & Reliability

• Connection Pooling: Maintains multiple SSH connections per server

• Command Queuing: Rate-limited command execution with priority support

• Real-time Streaming: Live output streaming for long-running commands

• Auto-Reconnection: Automatic reconnection with exponential backoff

• Health Monitoring: Continuous connection health checks

• Container Support: Enhanced init system detection for Docker/Podman environments

• Async Operations: Full async/await support for better performance

Quick Start

Prerequisites

• Python 3.9+

• SSH access to your VPS

• Claude Desktop or MCP-compatible client

Installation & Setup

# 1. Clone and install
git clone https://github.com/your-org/mcp-vps-manager.git
cd mcp-vps-manager
pip install -r requirements.txt

# 2. Configure your servers
cp templates/servers.yaml config/servers.yaml
# Edit config/servers.yaml with your server details

# 3. Add to Claude Desktop config
# See Configuration section for details

# 4. Test the connection
python bin/mcp-vps-manager --config config/servers.yaml --log-level DEBUG

First Commands

Ask Claude Desktop:

• "What servers do you have access to?"

• "Check the system status of my server"

• "List the files in /home"

Installation

Prerequisites

• Python 3.9+

• Poetry (for dependency management)

• SSH access to target VPS servers

• SSH keys configured for passwordless authentication

Install with Poetry

# Clone the repository
git clone <repository-url>
cd mcp-vps-manager

# Install dependencies
poetry install

# Activate the virtual environment
poetry shell

Install with pip

pip install mcp-vps-manager

Configuration

1. Server Configuration

Copy the example configuration file and customize it:

cp config/servers.yaml.example config/servers.yaml

Edit config/servers.yaml:

servers:
  - name: production-web
    host: 192.168.1.10
    port: 22
    username: admin
    ssh_key_path: ~/.ssh/id_rsa
    ssh_key_passphrase_env: SSH_KEY_PASS  # Optional
    allowed_paths:
      - /home/admin
      - /var/www
      - /etc/nginx
    blocked_commands:  # Additional patterns beyond defaults
      - shutdown
      - reboot
    max_file_size_mb: 50
    connection_timeout: 30
    command_timeout: 300

  - name: staging-db
    host: staging.example.com
    port: 2222
    username: dbadmin
    ssh_key_path: ~/.ssh/staging_key
    allowed_paths:
      - /home/dbadmin
      - /var/lib/mysql
      - /etc/mysql
    max_file_size_mb: 100

2. Environment Variables

Create a .env file (optional):

cp .env.example .env

Configure environment variables:

# SSH Key Passphrases (if needed)
SSH_KEY_PASS=your_ssh_key_passphrase_here

# Server Configuration
SERVERS_CONFIG_PATH=./config/servers.yaml

# Logging Configuration
LOG_LEVEL=INFO
LOG_DIR=./logs

# Connection Pool Settings
MAX_CONNECTIONS_PER_SERVER=3
HEALTH_CHECK_INTERVAL=30

3. Claude Desktop Integration

Add to your Claude Desktop MCP configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-vps-manager": {
      "command": "python",
      "args": ["-m", "vps_manager.server", "--config", "path/to/config/servers.yaml"],
      "env": {
        "SSH_KEY_PASS": "your_passphrase_if_needed"
      }
    }
  }
}

Usage

Starting the Server

# Using Poetry
poetry run mcp-vps-manager --config config/servers.yaml

# Using Python module
python -m vps_manager.server --config config/servers.yaml --log-level DEBUG

Available MCP Tools

1. exec_command

Execute shell commands on VPS servers with streaming and queuing support.

{
  "command": "ls -la /var/www",
  "server": "production-web",
  "timeout": 30,
  "background": false,
  "stream_output": false,
  "priority": "normal",
  "use_queue": true
}

New Parameters:

• stream_output (boolean): Enable real-time output streaming for long commands

• priority (string): Queue priority - "low", "normal", "high", or "critical"

• use_queue (boolean): Force use or bypass of the command queue system

2. read_file

Read file contents from VPS servers.

{
  "path": "/var/www/index.html",
  "server": "production-web",
  "encoding": "utf-8"
}

3. write_file

Write content to files on VPS servers.

{
  "path": "/var/www/new-page.html",
  "content": "<html><body>Hello World</body></html>",
  "server": "production-web",
  "create_dirs": true,
  "backup": true
}

4. upload_file

Upload files from local system to VPS.

{
  "local_path": "/local/file.txt",
  "remote_path": "/var/www/file.txt",
  "server": "production-web",
  "create_dirs": false
}

5. download_file

Download files from VPS to local system.

{
  "remote_path": "/var/log/app.log",
  "local_path": "/local/downloads/app.log",
  "server": "production-web"
}

6. get_system_status

Get comprehensive system metrics.

{
  "server": "production-web",
  "detailed": true
}

7. service_control

Control system services.

{
  "service_name": "nginx",
  "action": "restart",
  "server": "production-web",
  "force": false
}

8. list_services

List system services.

{
  "server": "production-web",
  "running_only": false,
  "pattern": "nginx.*"
}

9. get_service_logs

Retrieve service logs.

{
  "service_name": "nginx",
  "server": "production-web",
  "lines": 100
}

10. get_queue_status

Monitor command queue status and metrics.

{
  "server": "production-web"
}

Response includes:

• Queue size and execution metrics

• Rate limiting status

• Concurrent command counts

• Success/failure statistics

11. cleanup_queue_results

Clean up old command queue results to free memory.

{
  "max_age_hours": 24
}

Example Conversations with Claude

"Check the system status of my web server"

Using get_system_status tool on production-web server...

System Status:
- CPU Usage: 15.3% (4 cores)
- Memory: 3.2GB used / 8GB total (40%)
- Disk: 45GB used / 100GB total (45%)
- Load Average: 0.8, 0.6, 0.5
- Uptime: 15 days, 6 hours

"Restart nginx and check if it's running"

1. Using service_control to restart nginx...
   ✓ Nginx restarted successfully

2. Using service_control to check status...
   ✓ Nginx is active and running

3. Using exec_command to verify web server response...
   ✓ Web server responding on port 80

"Run a system update with real-time output"

Using exec_command with stream_output=true and high priority...

Starting system package update:
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
[Real-time streaming output continues...]
Fetching http://security.ubuntu.com/ubuntu jammy-security InRelease
Get:1 http://archive.ubuntu.com/ubuntu jammy InRelease [270 kB]
...
✓ Update completed successfully with streaming output

"Check command queue status across all servers"

Using get_queue_status tool...

Queue Status Summary:
- production-web: 2 commands queued, 1 executing, rate limit: 5/sec
- staging-db: 0 commands queued, 0 executing, rate limit: 3/sec
- monitoring: 1 command queued, 0 executing, rate limit: 10/sec

Total metrics: 15 commands executed, 2 failed, avg execution time: 1.2s

Security Best Practices

1. SSH Key Management

• Use dedicated SSH keys for MCP VPS Manager

• Store SSH key passphrases in environment variables

• Regularly rotate SSH keys

• Use Ed25519 keys when possible

2. Path Restrictions

• Limit allowed_paths to only necessary directories

• Avoid allowing access to system directories (/etc, /boot, /sys)

• Use absolute paths only

3. Command Blocking

• Review and customize blocked_commands for each server

• Test dangerous command blocking before production use

• Consider additional patterns specific to your environment

4. Network Security

• Use non-standard SSH ports when possible

• Implement SSH connection rate limiting

• Use VPN or private networks when available

5. Audit and Monitoring

• Enable audit logging in production

• Regularly review audit logs

• Monitor for unusual command patterns

• Set up alerts for security events

Troubleshooting

Common Issues

1. SSH Connection Failures

Error: Failed to connect test-server-1: [Errno 111] Connection refused

Solutions:

• Verify SSH service is running: systemctl status sshd

• Check firewall settings: ufw status or iptables -L

• Validate SSH key path and permissions

• Test manual SSH connection: ssh -i ~/.ssh/key user@host

2. Permission Denied Errors

Error: Command matches dangerous pattern: sudo\s+passwd

Solutions:

• Review blocked command patterns in security module

• Add exceptions to server configuration if needed

• Use force=true for administrative tasks (carefully)

• Check if command requires different permissions

3. Path Access Denied

Error: Path not in allowed directories: /etc/passwd

Solutions:

• Add required paths to allowed_paths in server configuration

• Use relative paths within allowed directories

• Check for typos in path specifications

• Verify directory exists and is accessible

4. File Size Limits

Error: File size 104857600 exceeds limit of 50MB

Solutions:

• Increase max_file_size_mb in server configuration

• Use chunked transfer for large files

• Consider compression before transfer

• Split large files into smaller parts

Debug Mode

Run with debug logging to troubleshoot issues:

python -m vps_manager.server --config config/servers.yaml --log-level DEBUG

Check logs in the configured log directory:

• debug.log: Detailed operation logs

• error.log: Error messages and stack traces

• audit.log: Command execution audit trail

Health Checks

Monitor connection pool health:

# The server exposes connection status via MCP resources
# Access vps://server-name resource in Claude to see connection status

Development

Setting up Development Environment

# Clone repository
git clone <repository-url>
cd mcp-vps-manager

# Install development dependencies
poetry install --with dev

# Run tests
poetry run pytest

# Run type checking
poetry run mypy src/

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

# Lint code
poetry run flake8 src/ tests/

Running Tests

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=src/vps_manager

# Run specific test file
poetry run pytest tests/unit/test_security.py

# Run integration tests (requires test environment)
poetry run pytest tests/integration/

Testing with Virtual Servers

For development and testing, you can use virtual machines or cloud instances with test configurations:

# Set up a test server with SSH access
# Create dedicated test user and SSH keys
ssh-keygen -t rsa -b 4096 -f ~/.ssh/test_key -C "test@example.com"

# Configure test server in servers.yaml
# Use appropriate port and credentials for your test environment

Architecture

Component Overview

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Claude/LLM    │───▶│  MCP VPS Server  │───▶│  VPS Servers    │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
                    ┌──────────────────┐
                    │  Security Layer  │
                    │  Connection Pool │
                    │  Audit Logging   │
                    └──────────────────┘

Key Components

1. MCP Server (server.py): Main MCP protocol handler

2. Connection Pool (connection_pool.py): SSH connection management with health checks

3. Command Queue (queue.py): Priority-based command queuing and rate limiting

4. Security Validator (security.py): Command and path validation

5. Enhanced Tools: Individual operation handlers

   • Command execution with streaming (tools/command.py)

   • File operations (tools/file_ops.py)

   • System monitoring (tools/monitoring.py)

   • Container-aware service management (tools/services.py)

6. Enhanced Utilities:

   • Container-aware init system detection (utils/distro.py)

   • Secure sudo handling (utils/secure_sudo.py)

   • Error handling and MCP responses (utils/error_handling.py, utils/mcp_responses.py)

Changelog

v0.2.0 (Latest - GitHub Issues Fix Release)

• Real-time Command Streaming: Live output streaming for long-running commands

• Command Queuing System: Priority-based queuing with rate limiting and concurrency control

• Container-aware Init Detection: Enhanced systemd detection for Docker/Podman environments

• Queue Management Tools: New MCP tools for monitoring and managing command queues

• Enhanced Error Handling: Improved error messages and graceful fallbacks

• Performance Optimizations: Better resource management and connection pooling

v0.1.0 (Initial Release)

• MCP protocol implementation

• SSH connection pooling

• Security validation system

• File operations via SFTP

• System monitoring tools

• Service management

• Comprehensive test suite

• Documentation

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests for new functionality

5. Ensure all tests pass

6. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• GitHub Issues: Report bugs and request features

• Documentation: This README and inline code documentation

• Security Issues: Report privately via email

Table of Contents

• Quick Start

• Installation

• Configuration

• Usage

• Security Best Practices

• Troubleshooting

• Development

• Architecture

• Contributing

• Support

Related Projects

• MCP Python SDK - MCP Python implementation

• Claude Desktop - MCP client with desktop app

• Other MCP Servers - Community MCP servers

Additional Resources

• INSTALL.md - Detailed installation guide

• SECURITY.md - Comprehensive security guide and best practices

• Templates - Configuration templates

• Examples - Usage examples and integrations

Version History

v0.2.0 (Current - GitHub Issues Fix Release)

• Real-time command output streaming

• Priority-based command queuing with rate limiting

• Container-aware init system detection (Docker/Podman)

• Queue monitoring and management tools

• Enhanced streaming for long-running operations

• Improved error handling and graceful fallbacks

• Performance optimizations and resource management

v0.1.0 (Previous)

• MCP protocol implementation

• SSH connection pooling with health checks

• Comprehensive security validation

• File operations via SFTP

• System monitoring and metrics

• Service management (systemd/sysv/upstart)

• Enhanced error handling and user feedback

• Production packaging and deployment

• Complete test suite

• Documentation and security guides

Roadmap

• Web UI for server management

• Metrics dashboard and real-time monitoring

• Multi-factor authentication support

• Container management integration (Docker/K8s)

• Backup and restoration tools

• Advanced queue scheduling and automation

Acknowledgments

• Model Context Protocol for the MCP specification

• AsyncSSH for robust SSH connectivity

• Pydantic for configuration validation

• Claude Desktop for MCP client support

• The open source community for inspiration and contributions

Made with love for the MCP community

Securely manage your VPS infrastructure with AI assistance