# VPS.org MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that connects AI assistants to the VPS.org API. Manage VPS servers, domains, DNS records, SSH keys, and more through natural language.

## Install

```bash
# Recommended: run directly with uvx (no install needed)
uvx vps-mcp

# Or install with pip
pip install vps-mcp
```

## Get Your API Token

1. Log in at [admin.vps.org](https://admin.vps.org)
2. Go to **Account → Developers** ([direct link](https://admin.vps.org/account/developers/))
3. Create a new API token
4. Copy the token (starts with `vps_`)

## Configuration

### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "vps": {
      "command": "uvx",
      "args": ["vps-mcp"],
      "env": {
        "VPS_API_TOKEN": "vps_your_token_here"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add vps -- uvx vps-mcp
```

Then set the environment variable before running Claude Code:

```bash
export VPS_API_TOKEN="vps_your_token_here"
```

### Custom API URL

If you need to point to a different API endpoint:

```json
{
  "env": {
    "VPS_API_TOKEN": "vps_your_token_here",
    "VPS_API_URL": "https://admin.vps.org/api/v1"
  }
}
```

## Tools

### Servers

| Tool | Description |
|------|-------------|
| `list_servers` | List all VPS servers in your account |
| `get_server` | Get detailed info about a specific server |
| `create_server` | Create a new VPS server |
| `delete_server` | Permanently delete a server |
| `server_power` | Start, stop, restart, or hard-stop a server |
| `create_backup` | Create a backup of a server |
| `create_snapshot` | Create a snapshot of a server |
| `resize_server` | Resize a server to a different plan |

### Domains

| Tool | Description |
|------|-------------|
| `list_domains` | List all domains in your account |
| `get_domain` | Get detailed info about a domain |
| `search_domains` | Search for domain availability |
| `update_nameservers` | Update nameservers for a domain |
| `renew_domain` | Renew a domain registration |

### DNS

| Tool | Description |
|------|-------------|
| `list_dns_zones` | List DNS zones (optionally filter by domain) |
| `get_dns_zone` | Get a DNS zone with all records |
| `create_dns_zone` | Create a new DNS zone |
| `delete_dns_zone` | Delete a DNS zone and all its records |
| `create_dns_record` | Create a DNS record (A, AAAA, CNAME, MX, TXT, etc.) |
| `update_dns_record` | Update an existing DNS record |
| `delete_dns_record` | Delete a DNS record |

### Info

| Tool | Description |
|------|-------------|
| `list_plans` | List available VPS plans with pricing |
| `list_locations` | List available data center locations |
| `list_operating_systems` | List available OS options |

### SSH Keys

| Tool | Description |
|------|-------------|
| `list_ssh_keys` | List all SSH keys in your account |
| `add_ssh_key` | Add a new SSH public key |
| `delete_ssh_key` | Delete an SSH key |

## Required API Permissions

Your API token needs the following permissions depending on which tools you use:

| Tools | Required Permission |
|-------|-------------------|
| Server tools | `servers:*` |
| Domain tools | `domains:*` |
| DNS tools | `dns:*` |
| Plan/Location/OS tools | `servers:read` |
| SSH Key tools | `ssh_keys:*` |
| All tools | `*:*` |

## Examples

Once configured, you can ask your AI assistant things like:

- "List my VPS servers"
- "Create a new Ubuntu server in Amsterdam with the starter plan"
- "Stop server abc-123"
- "Add an A record for api.example.com pointing to 1.2.3.4"
- "What plans are available?"
- "Add my SSH key to the account"

## Development

```bash
# Clone the repo
git clone https://github.com/vpsdotorg/vps-mcp.git
cd vps-mcp

# Install in development mode
uv sync

# Run the server locally
VPS_API_TOKEN=your_token uv run vps-mcp
```

## License

MIT