Contabo MCP MCP Server

Contabo MCP Server

MCP (Model Context Protocol) server for the Contabo API. Manage virtual machines, images, snapshots/backups, networking, DNS, object storage, secrets, domains, and tags from Cursor or other MCP clients.

Features

• 115 tools with contabo_* naming
• Two transports: stdio (default) and remote Streamable HTTP with Bearer-token auth (Docker-ready — see Remote HTTP transport)
• OAuth2 password grant (or static bearer token for development)
• Automatic x-request-id per request and token refresh on 401
• Secret value redaction in tool responses (secrets and S3 credentials)
• MCP tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) on all tools
• Structured error payloads with x-request-id and audit-tool hints

Security and Socket

This package is an API client: it reads CONTABO_* environment variables and calls Contabo over HTTPS only. Outbound hosts are restricted to *.contabo.com unless CONTABO_ALLOW_CUSTOM_HOSTS=true (staging). See SECURITY.md for the full allowlist and reporting process.

The Socket.dev badge may show network access, environment variable access, URL strings, and GPL license alerts — these are intentional for this package type, not indicators of malware. Dependency CVEs are tracked via pnpm audit in CI.

Tool annotations

Every tool sets MCP hints so clients can warn before destructive calls:

Errors return structured JSON (structuredContent.error) with code, message, status, and xRequestId.

Releases

Versioning and npm publish are automated with release-please on main. Any conventional commit under contabo-mcp/ updates the next release pull request. See CONTRIBUTING.md in the repository root.

Prerequisites

1. Node.js 20 or newer
2. Contabo API credentials (see Obtaining API credentials below)
3. Optional background: Contabo help — How can I access the Contabo API?

Obtaining API credentials

All values come from the Contabo Customer Control Panel. You need a normal control-panel login (including 2FA if enabled).

Open the API page

1. Sign in at my.contabo.com.
2. Open API details (menu path may vary; the direct URL is stable).

The page title is API. It states that the data shown there plus the API password are required to use the API.

Fields on the API page

The panel lists four pieces of information (labels may appear in German or English depending on locale):

Set the API password (required once)

Until you set an API password, the panel typically asks you to set a new password before you can use the API (“Bitte setzen Sie ein neues Passwort, um die API nutzen zu können”).

1. On API details, use the control to set or change the API password.
2. Choose a strong password and store it in a password manager.
3. Use that value for CONTABO_API_PASSWORD — not your normal my.contabo.com login password.

You can change the API password anytime in the same place.

Map credentials to this MCP server

Copy the four values into .env (local development) or your MCP client env block:

CONTABO_CLIENT_ID=DE-XXXX          # Customer ID from the panel
CONTABO_CLIENT_SECRET=...          # Client secret (full string)
CONTABO_API_USER=you@example.com   # Username from the panel
CONTABO_API_PASSWORD=...           # API password you set on the API page

Example .cursor/mcp.json fragment:

"env": {
  "CONTABO_CLIENT_ID": "DE-XXXX",
  "CONTABO_CLIENT_SECRET": "your-client-secret",
  "CONTABO_API_USER": "you@example.com",
  "CONTABO_API_PASSWORD": "your-api-password"
}

Verify credentials

After saving config, restart the MCP client (or reload MCP servers in Cursor). A quick check:

• OAuth errors such as unauthorized_client / Invalid client credentials usually mean a wrong Customer ID or Client secret.
• invalid_grant or login-related errors often mean a wrong API user or API password (e.g. using the control-panel login password instead of the API password).

Do not commit .env or paste secrets into chat, issues, or screenshots.

Install as a Claude Code plugin

/plugin marketplace add kieksme/mcp-contabo
/plugin install contabo-mcp@mcp-contabo

Claude Code prompts you for the four credentials from Obtaining API credentials above when you enable the plugin and stores them in the OS credential store (or a Claude-managed fallback on platforms without one) rather than in a plaintext .mcp.json or settings file. Runs the same published npm package under the hood via npx.

Install from npm (recommended)

Published as @kieksme/contabo-mcp on npm under the kieksme account. No clone and no build step required.

Cursor / MCP client

Add to .cursor/mcp.json (or your global MCP config):

{
  "mcpServers": {
    "contabo": {
      "command": "npx",
      "args": ["-y", "@kieksme/contabo-mcp"],
      "env": {
        "CONTABO_CLIENT_ID": "your-client-id",
        "CONTABO_CLIENT_SECRET": "your-client-secret",
        "CONTABO_API_USER": "your-api-user@email.com",
        "CONTABO_API_PASSWORD": "your-api-password"
      }
    }
  }
}

With pnpm:

{
  "mcpServers": {
    "contabo": {
      "command": "pnpm",
      "args": ["dlx", "@kieksme/contabo-mcp"],
      "env": {
        "CONTABO_CLIENT_ID": "your-client-id",
        "CONTABO_CLIENT_SECRET": "your-client-secret",
        "CONTABO_API_USER": "your-api-user@email.com",
        "CONTABO_API_PASSWORD": "your-api-password"
      }
    }
  }
}

See mcp.json.example for more variants.

Terminal (stdio)

npx -y @kieksme/contabo-mcp

pnpm dlx @kieksme/contabo-mcp

Global install

npm install -g @kieksme/contabo-mcp
contabo-mcp

Install from GitHub Packages (alternative)

The same package is also mirrored to GitHub Packages. npm remains the recommended source — GitHub Packages requires authentication even for public packages, so it is only worth using if your organization already standardizes on GitHub Packages.

1. Create a GitHub personal access token (classic) with the read:packages scope.

2. Point the @kieksme scope at GitHub Packages in your ~/.npmrc:

   @kieksme:registry=https://npm.pkg.github.com
   //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
   

   (Set GITHUB_TOKEN in your environment, or inline the token value.)

3. Install as usual:

   npm install @kieksme/contabo-mcp     # or: npm install -g @kieksme/contabo-mcp
   

Install from GitHub (alternative)

Without npm, install from the repository (first run builds the package; requires pnpm via Corepack on Node 20+):

{
  "mcpServers": {
    "contabo": {
      "command": "npx",
      "args": [
        "-y",
        "--package=git+https://github.com/kieksme/mcp-contabo.git#main",
        "contabo-mcp"
      ],
      "env": { "...": "..." }
    }
  }
}

npx -y --package=git+https://github.com/kieksme/mcp-contabo.git#main contabo-mcp

Remote HTTP transport (Docker)

Besides stdio, the server can run as a remote MCP over Streamable HTTP, authenticated with a Bearer token. This is the mode used in Docker. Behavior is selected via MCP_TRANSPORT (default stdio, fully backward compatible).

Configuration

The Contabo API credentials (CONTABO_*) are still required — the HTTP transport only changes how MCP clients reach the server, not how it authenticates to Contabo.

Run with Docker Compose

cp .env.example .env      # fill in CONTABO_* and set MCP_AUTH_TOKEN
docker compose up --build

The server listens on http://localhost:3000/. An unauthenticated GET /health returns {"status":"ok"} for container/orchestrator probes.

Pull the published image (GHCR)

Released versions are published to the GitHub Container Registry as public images, tagged with the version number (and latest for the newest release):

docker run --rm -p 3000:3000 \
  -e MCP_AUTH_TOKEN=... \
  -e CONTABO_CLIENT_ID=... -e CONTABO_CLIENT_SECRET=... \
  -e CONTABO_API_USER=... -e CONTABO_API_PASSWORD=... \
  ghcr.io/kieksme/contabo-mcp:latest        # or :1.4.0

Maintainers: a GHCR package is private on first publish. Set its visibility to public once under the package settings (https://github.com/users/kieksme/packages/container/contabo-mcp/settings).

Deploy on Railway

railway.json in this directory carries the Config as Code settings (Dockerfile builder, /health healthcheck, restart policy) so Railway picks up the same image the Docker Compose and GHCR flows above use.

Manual deploy:

1. On railway.com/new, choose Deploy from GitHub repo and pick kieksme/mcp-contabo.
2. Service Settings:
   • Root Directory: contabo-mcp — this repo is a pnpm monorepo, so Railway must build from the package directory, not the repo root.
   • Config File Path: /contabo-mcp/railway.json — this path is always relative to the repo root and ignores Root Directory (see monorepo config-as-code).
   • Networking → Public Networking: Generate Domain, target port 3000.
3. Service Variables — the four CONTABO_* credentials (see Obtaining API credentials) plus:

   MCP_TRANSPORT=http
   MCP_HTTP_HOST=0.0.0.0
   MCP_HTTP_PORT=3000
   MCP_AUTH_TOKEN=<random value, e.g. `openssl rand -hex 32`>
   

4. Deploy, then point an MCP client at https://<your-domain>.up.railway.app/ with Authorization: Bearer <MCP_AUTH_TOKEN> — see Connect an MCP client below.

Scaling: keep replicas at 1. Sessions are held in-memory (see Security notes) and Railway does not provide sticky sessions across replicas for Streamable HTTP.

Publishing this as a Railway template (maintainers)

Turning the manual deploy above into a one-click marketplace template is a dashboard-only action — Railway's CLI/API does not expose template creation, so it can't be scripted:

1. Deploy manually once (steps above) and confirm /health responds and an MCP client can connect through the generated domain.
2. On that project: Settings → Generate Template from Project (or start fresh under Templates → New Template).
3. In the template composer, on the contabo-mcp service:
   • Keep Root Directory = contabo-mcp and Config File Path = /contabo-mcp/railway.json.
   • Replace the four CONTABO_* values with empty, marked-required template variables — never bake real credentials into a published template.
   • Set MCP_AUTH_TOKEN to the template variable function ${{secret(64, "abcdef0123456789")}} so each deploy gets its own random token instead of a shared default.
   • Confirm Public Networking (HTTP, port 3000) and Healthcheck Path (/health) are set.
4. Create Template, then Publish it from the Templates page to list it on the marketplace.
5. Copy the resulting template URL/code and use it to build the Deploy on Railway button in this README and the root README.

Connect an MCP client

{
  "mcpServers": {
    "contabo-remote": {
      "type": "streamable-http",
      "url": "https://your-host:3000/",
      "headers": { "Authorization": "Bearer <MCP_AUTH_TOKEN>" }
    }
  }
}

For stdio-only clients, bridge with mcp-remote:

npx -y mcp-remote https://your-host:3000/ --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

Clients must send Accept: application/json, text/event-stream; a plain curl without it gets 406.

Security notes

• TLS: the server speaks plain HTTP. Terminate TLS at a reverse proxy / ingress and never expose the raw port to the internet unencrypted.
• Scaling: sessions are held in-memory (stateful). Behind multiple replicas, enable sticky sessions at the load balancer so a client stays on the instance that holds its Mcp-Session-Id.
• Enable MCP_HTTP_DNS_REBINDING_PROTECTION with MCP_HTTP_ALLOWED_HOSTS for any deployment reachable beyond localhost.

Evaluations

Read-only evaluation scenarios for agent testing live in evaluations/contabo.eval.xml. Regenerate answers against your account when adding live-data questions.

Contributing

Development setup, testing, OpenAPI refresh, and release process: see CONTRIBUTING.md in the repository root.

Tool inventory

Automated VM backups: use contabo_instances_upgrade with body { "backup": {} }.

Object storage S3 credentials require userId (Contabo user UUID from the control panel).

License

GPL-3.0-or-later (see LICENSE).