🖥️ VPS MCP Server

An MCP (Model Context Protocol) server that gives AI assistants full control over a VPS via SSH. Execute commands, manage files, control services, monitor resources, manage Docker containers, and configure firewalls — all through a secure SSH tunnel.

✨ Features

| Tool | Description | |------|-------------| | run_command | Execute any shell command on the VPS | | read_file | Read file contents via SFTP | | write_file | Create or overwrite files via SFTP | | list_directory | List directory contents with detailed info | | manage_service | Start, stop, restart, reload, enable, disable systemd services & view logs | | list_services | List systemd services filtered by state (running, failed, enabled) | | system_stats | Get CPU, memory, disk, network, uptime, and process stats | | docker | Manage Docker containers — list, start, stop, restart, logs, stats, images | | firewall | Manage UFW rules — status, allow, deny, delete, reset |

📦 Installation

# Clone the repository
git clone https://github.com/your-username/vps-mcp-server.git
cd vps-mcp-server

# Install dependencies
pnpm install

# Build
pnpm build

⚙️ Configuration

Create a .env file from the example:

cp .env.example .env

Set the following environment variables:

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | VPS_HOST | ✅ | — | Hostname or IP of your VPS | | VPS_USER | ✅ | — | SSH username | | VPS_KEY_PATH | ✅ | — | Absolute path to your SSH private key | | VPS_PORT | ❌ | 22 | SSH port | | VPS_KEY_PASSPHRASE | ❌ | — | Passphrase for the SSH key (if encrypted) |

Example .env:

VPS_HOST=203.0.113.10
VPS_USER=deploy
VPS_KEY_PATH=/Users/you/.ssh/id_ed25519
VPS_PORT=22

🚀 Usage

With Claude Desktop / Gemini CLI / Any MCP Client

Add the server to your MCP client configuration:

{
  "mcpServers": {
    "vps": {
      "command": "node",
      "args": ["/absolute/path/to/vps-mcp-server/dist/index.js"],
      "env": {
        "VPS_HOST": "203.0.113.10",
        "VPS_USER": "deploy",
        "VPS_KEY_PATH": "/Users/you/.ssh/id_ed25519"
      }
    }
  }
}

Development Mode

pnpm dev

Production

pnpm build
pnpm start

🛠️ Tools Reference

`run_command`

Execute a shell command on the VPS.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | command | string | ✅ | — | The shell command to execute | | timeout | number | ❌ | 30000 | Timeout in milliseconds | | working_directory | string | ❌ | — | Directory to run the command in |

Returns: JSON with exit_code, stdout, and stderr.

---

`read_file`

Read the contents of a file on the VPS via SFTP.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | path | string | ✅ | — | Absolute path to the file | | max_lines | number | ❌ | — | Max lines to return (omit for full file) |

---

`write_file`

Write content to a file on the VPS via SFTP.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | path | string | ✅ | — | Absolute path to the file | | content | string | ✅ | — | Content to write | | create_dirs | boolean | ❌ | false | Create parent directories if missing |

---

`list_directory`

List files and directories at a given path.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | path | string | ❌ | / | Directory path to list | | show_hidden | boolean | ❌ | false | Include dotfiles | | long_format | boolean | ❌ | true | Show permissions, size, date |

---

`manage_service`

Manage systemd services.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | service | string | ✅ | — | Service name (e.g., nginx) | | action | enum | ✅ | — | start \| stop \| restart \| reload \| status \| enable \| disable \| logs | | log_lines | number | ❌ | 50 | Lines to show (for logs action) |

---

`list_services`

List systemd services filtered by state.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | filter | enum | ❌ | running | all \| running \| failed \| enabled |

---

`system_stats`

Get system resource usage.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | include | array | ❌ | ["all"] | cpu \| memory \| disk \| network \| uptime \| processes \| all |

---

`docker`

Manage Docker containers.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | action | enum | ✅ | — | ps \| start \| stop \| restart \| logs \| stats \| images | | container | string | ❌ | — | Container name/ID (required for start/stop/restart/logs) | | log_lines | number | ❌ | 50 | Lines to show (for logs action) |

---

`firewall`

Manage UFW firewall rules.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | action | enum | ✅ | — | status \| allow \| deny \| delete \| reset | | rule | string | ❌ | — | Rule spec (e.g., 80/tcp, 443, from 10.0.0.1) |

📁 Project Structure

src/
├── index.ts            # Server bootstrap & lifecycle
├── ssh.ts              # SSHManager class (connection pooling)
├── types.ts            # Shared TypeScript types
├── helpers.ts          # Response helper functions
└── tools/
    ├── index.ts         # Tool registration barrel
    ├── run-command.ts   # Shell command execution
    ├── read-file.ts     # SFTP file reading
    ├── write-file.ts    # SFTP file writing
    ├── list-directory.ts
    ├── manage-service.ts
    ├── list-services.ts
    ├── system-stats.ts
    ├── docker.ts
    └── firewall.ts

🔒 Security Notes

The server connects via SSH using key-based authentication (no passwords).
Commands run with the privileges of the configured SSH user.
Service management and firewall tools use sudo — ensure your SSH user has appropriate sudoers permissions.
The server maintains a persistent SSH connection that is automatically reconnected if dropped.

📄 License

MIT

vps-mcp-server