@rarecloudio/mcp-server

Model Context Protocol server for the RareCloud API.

Drop into Claude Code, Claude Desktop, Cursor, or your own MCP client to let AI agents inspect and reason about your RareCloud account — list servers, browse the catalog, check billing, plan deployments.

What it does

Exposes 20 read-only tools wrapping the RareCloud REST API:

| Category | Tool | Purpose | |---|---|---| | Catalog | list_catalog_products | Browse orderable plans, filter by kind/backend | | | get_catalog_plan | Full plan detail: specs + pricing + billing tracks | | | list_regions | Available datacenter regions | | | list_images | OS images (Ubuntu / Debian / Windows / ...) | | Services | list_services | All your running services (filter by category) | | | get_service | Detail on one service | | | get_service_metrics | CPU / RAM / disk / bandwidth time series | | | list_backups | Backups for one legacy VPS | | | get_provisioning_state | Setup state of a pending service (paid / unprovisioned / stuck) | | | list_os_templates | OS templates a legacy VPS can be reinstalled with | | | list_upgrade_options | Plans+cycles a service could upgrade/downgrade to | | Billing | list_invoices | Invoice history | | | get_invoice | Detail on one invoice | | | get_credit_balance | Current prepaid credit | | | get_credit_ledger | Credit movements (top-ups, vouchers, metering) | | Support | list_tickets | Support tickets (filter by status) | | | get_ticket | One ticket with its full thread | | Account | get_account | Profile (email, name, country) | | | list_ssh_keys | SSH keys on a server (per-service) | | | get_account_limits | Resource caps + current usage |

Read-only by design

This release is read-only. No create_server, no destroy, no snapshot create. The reason is architectural: mutating actions need a derived, scoped token plus a mandatory plan-and-approve step before they're safe to expose to an LLM. That ships in a future release.

In the meantime: the agent can read, recommend, and generate Terraform/CLI commands. The user copy-pastes them or runs them via the RareCloud CLI.

Install

Requires Node.js 20+.

npm install -g @rarecloudio/mcp-server

Or run directly with npx:

npx @rarecloudio/mcp-server

Configure

Get an API token: Dashboard → Account → API tokens → New token. Scope it to read-only (services:read, billing:read, account:read, catalog:read). Copy it — shown once.

Set the env var:

export RARECLOUD_API_TOKEN="rc_pat_..."

Optional, for self-hosted / staging instances:

export RARECLOUD_API_ENDPOINT="https://your-instance.example.com"

Use with Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "rarecloud": {
      "command": "npx",
      "args": ["-y", "@rarecloudio/mcp-server"],
      "env": {
        "RARECLOUD_API_TOKEN": "rc_pat_..."
      }
    }
  }
}

Restart Claude Desktop. The 20 tools become available under the 🔌 menu.

Use with Claude Code

claude mcp add rarecloud npx -- -y @rarecloudio/mcp-server \
  -e RARECLOUD_API_TOKEN=rc_pat_...

Use with Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "rarecloud": {
      "command": "npx",
      "args": ["-y", "@rarecloudio/mcp-server"],
      "env": { "RARECLOUD_API_TOKEN": "rc_pat_..." }
    }
  }
}

Example prompts

Once configured, try:

• "What VPS plans do you offer in Frankfurt?" → uses list_catalog_products + list_regions
• "List my running servers and their monthly cost" → list_services + per-service spec lookup
• "Am I close to any resource limits?" → get_account_limits
• "Give me a Terraform config for a 2 vCPU / 4 GB VPS in The Hague" → get_catalog_plan + composition

Develop locally

git clone https://github.com/RareCloudio/rarecloud-mcp-server
cd rarecloud-mcp-server
npm install
npm run dev      # runs from source via tsx
npm run build    # compiles to dist/

Then point Claude Desktop at your local checkout:

{
  "mcpServers": {
    "rarecloud-dev": {
      "command": "node",
      "args": ["/absolute/path/to/rarecloud-io/mcp-server/dist/index.js"],
      "env": { "RARECLOUD_API_TOKEN": "rc_pat_..." }
    }
  }
}

Security

• Tokens never touch shell history (we use env vars, not CLI flags).
• Each tool maps 1:1 to a RareCloud API endpoint; the MCP server doesn't aggregate or transform data beyond what the API returns.
• Read-only scope — there is no path for an agent to mutate state via this server, even on a compromised token.
• Revoke a token at any time: Dashboard → Account → API tokens. Revocation is instant, no propagation delay.

License

MIT.