MCP VPS Initialize

A Model Context Protocol (MCP) server for automated VPS initialization and management. This tool provides SSH-based automation for setting up fresh VPS instances with common services and CI/CD pipelines.

Features

• 🔐 SSH Authentication: Supports both password and private key authentication

• 🛠️ VPS Initialization: Automated setup of Node.js, PM2, Rust, Nginx, Redis

• 🌐 Nginx Configuration: Domain setup with reverse proxy and SSL certificates

• 🚀 GitHub CI/CD: Automated deploy key generation and workflow creation

• 📝 Comprehensive Logging: Winston-based structured logging

• 🔧 TypeScript: Fully typed with strict TypeScript configuration

Related MCP server: mcp-git

Installation

Development

MCP Tools

1. SSH Connect

Connect to a VPS via SSH using password or private key authentication.

Parameters:

• host (required): VPS IP address or hostname

• username (required): SSH username

• port (optional): SSH port (default: 22)

• password (optional): SSH password

• privateKeyPath (optional): Path to private key file

• passphrase (optional): Private key passphrase

Example:

2. VPS Initialize

Initialize a fresh VPS with system updates and optional services.

Parameters:

• services (optional): Object specifying which services to install

  • nodejs (boolean): Install Node.js LTS

  • pm2 (boolean): Install PM2 process manager

  • rust (boolean): Install Rust toolchain

  • nginx (boolean): Install and configure Nginx

  • redis (boolean): Install and configure Redis

Example:

3. Nginx Setup

Configure Nginx with domain, reverse proxy, and SSL certificates.

Parameters:

• domain (required): Domain name for the site

• port (required): Backend port to proxy requests to

• ssl (optional): Enable SSL with Certbot (default: true)

Example:

4. GitHub CI/CD Setup

Setup GitHub CI/CD with deploy keys and automated workflows.

Parameters:

• repoUrl (required): GitHub repository URL

• deployPath (required): Deployment path on the server

Example:

5. Execute Command

Execute arbitrary commands on the connected VPS.

Parameters:

• command (required): Command to execute

Example:

Workflow

Basic VPS Setup

1. Connect to VPS:

   { "tool": "ssh_connect", "args": { "host": "your-vps-ip", "username": "root", "password": "your-password" } }

2. Initialize VPS:

   { "tool": "vps_initialize", "args": { "services": { "nodejs": true, "pm2": true, "nginx": true } } }

3. Setup Nginx:

   { "tool": "nginx_setup", "args": { "domain": "yourdomain.com", "port": 3000, "ssl": true } }

4. Setup CI/CD:

   { "tool": "github_cicd_setup", "args": { "repoUrl": "https://github.com/username/repo.git", "deployPath": "/opt/deployments/myapp" } }

GitHub CI/CD Instructions

After running the github_cicd_setup tool, you'll receive:

1. Deploy Key: Add to your GitHub repository's Deploy Keys

2. GitHub Secrets: Add to your repository's Actions secrets

3. Workflow File: Add to .github/workflows/deploy.yml

The generated workflow will:

• Trigger on pushes to main/master branch

• Run tests (if available)

• Build the application (if build script exists)

• Deploy to your VPS automatically

Security Features

• Firewall Configuration: Automatic UFW setup with secure defaults

• SSL Certificates: Automated Let's Encrypt certificate generation

• SSH Key Management: Secure deploy key generation

• Process Isolation: Optional deploy user creation

Logging

Logs are written to:

• logs/combined.log: All log levels

• logs/error.log: Error logs only

• Console: Formatted output with colors

Log levels: error, warn, info, debug

Configuration

The server can be configured through environment variables:

• LOG_LEVEL: Set logging level (default: 'info')

• PORT: Server port (if running standalone)

Troubleshooting

Common Issues

1. SSH Connection Failed

   • Verify IP address and credentials

   • Check firewall settings

   • Ensure SSH service is running

2. SSL Certificate Issues

   • Verify domain DNS points to server

   • Check firewall allows HTTP/HTTPS

   • Ensure email is valid for Let's Encrypt

3. Service Installation Failed

   • Check system update status

   • Verify internet connectivity

   • Review error logs

Debug Mode

Enable debug logging:

Requirements

• Node.js 18+

• Fresh Ubuntu/Debian VPS

• Domain name (for SSL setup)

• GitHub repository (for CI/CD)

License

MIT License - see LICENSE file for details.