# 🖥️ VPS MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) 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

```bash
# 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:

```bash
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`:**

```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:

```json
{
  "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

```bash
pnpm dev
```

### Production

```bash
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