Skip to main content
Glama

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: ssh-alias-mcp

Installation

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

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

Development

# Run in development mode
npm run dev

# Lint code
npm run lint
npm run lint:fix

# Format code
npm run format
npm run format:check

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:

{
  "host": "192.168.1.100",
  "username": "root",
  "password": "your-password"
}

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:

{
  "services": {
    "nodejs": true,
    "pm2": true,
    "nginx": true,
    "redis": false
  }
}

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:

{
  "domain": "example.com",
  "port": 3000,
  "ssl": true
}

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:

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

5. Execute Command

Execute arbitrary commands on the connected VPS.

Parameters:

  • command (required): Command to execute

Example:

{
  "command": "systemctl status nginx"
}

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:

LOG_LEVEL=debug npm start

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.

Available Tools

5 tools
execute_commandC

Execute a command on the connected VPS

Inputs: command (required).

github_cicd_setupC

Setup GitHub CI/CD with deploy keys and workflow

Inputs: repoUrl (required), deployPath (required).

nginx_setupC

Configure Nginx with domain, reverse proxy, and SSL

Inputs: domain (required), port (required), ssl.

ssh_connectC

Connect to a VPS via SSH using password or private key

Inputs: host (required), username (required), port, password, +2 more.

vps_initializeC

Initialize a fresh VPS with basic setup and optional services

Inputs: services.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: execute_command runs commands, github_cicd_setup configures CI/CD, nginx_setup handles web server setup, ssh_connect establishes SSH connections, and vps_initialize performs initial VPS setup. There is no overlap or ambiguity between these functions.

    Naming Consistency4/5

    Most tools follow a consistent verb_noun pattern (e.g., execute_command, nginx_setup, ssh_connect), but github_cicd_setup uses an acronym and vps_initialize includes 'vps' as a prefix, which slightly deviates from the pattern. Overall, the naming is readable and mostly predictable.

    Tool Count5/5

    With 5 tools, the server is well-scoped for VPS initialization tasks. Each tool serves a specific, necessary function in the setup process, from connecting to the VPS to configuring services, making the count appropriate and efficient.

    Completeness4/5

    The toolset covers core VPS initialization workflows, including connection, basic setup, command execution, web server configuration, and CI/CD integration. A minor gap might be the lack of tools for monitoring or backup setup, but agents can work around this with existing tools.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables LLMs to securely manage Virtual Private Servers via SSH, with features including command execution, file operations, system monitoring, and service management.
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to SSH into Linux servers, run commands, deploy code, and manage servers via natural language, also doubles as a CLI for manual use.
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables SSH command execution, file uploads/downloads, and multi-server management with zero-config inline credentials, supporting async jobs and AI-readable output.
      32 npm
      2
      AGPL 3.0