# Contabo MCP

**Give Claude full operational control over your Contabo VPS/VDS infrastructure.**
**أعطِ Claude تحكمًا كاملًا في بنيتك التحتية على Contabo.**

A Model Context Protocol (MCP) server for [Contabo](https://contabo.com) — 57 tools across instances, DNS, snapshots, tags, networks, secrets, users, domains, images, PTR records, and audit logs. Plug it into Claude Desktop and ask Claude to provision, scale, snapshot, or audit your servers in natural language.

[![npm](https://img.shields.io/npm/v/@smorchestraai-code/contabo-mcp.svg)](https://www.npmjs.com/package/@smorchestraai-code/contabo-mcp)
[![CI](https://github.com/SMOrchestra-ai/contabo-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/SMOrchestra-ai/contabo-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

---

## Install in one minute

You need: **Node.js 20 or newer** (download from [nodejs.org](https://nodejs.org/)) and **Claude Desktop**.

**1. Find your Claude Desktop config file:**

| OS | Path |
|---|---|
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |

If the file doesn't exist, create it.

**2. Paste this block** (replace the four placeholders with your Contabo API credentials):

```json
{
  "mcpServers": {
    "contabo": {
      "command": "npx",
      "args": ["-y", "@smorchestraai-code/contabo-mcp"],
      "env": {
        "CONTABO_CLIENT_ID": "your-client-id-here",
        "CONTABO_CLIENT_SECRET": "your-client-secret-here",
        "CONTABO_API_USER": "your-api-user-email-here",
        "CONTABO_API_PASSWORD": "your-api-password-here"
      }
    }
  }
}
```

**3. Restart Claude Desktop.** Open a new chat and ask *"list my Contabo instances"* — Claude should respond with your VPS list.

> **Platform-specific walkthroughs:** [Windows](docs/install-windows.md) · [macOS](docs/install-mac.md) · [Troubleshooting](docs/troubleshooting.md)

---

## Where to get your Contabo credentials

1. Sign in to [my.contabo.com](https://my.contabo.com)
2. Go to **Account → API**
3. Click **Create API user** if you don't have one
4. Copy the four values into the config above:
   - `CONTABO_CLIENT_ID` — shown as "Client ID"
   - `CONTABO_CLIENT_SECRET` — shown as "Client Secret"
   - `CONTABO_API_USER` — the email address of the API user
   - `CONTABO_API_PASSWORD` — the password you set for the API user

> **Privacy:** these credentials live ONLY in your local Claude Desktop config on YOUR machine. SMOrchestra never sees them. The MCP server uses Contabo's OAuth 2.0 ROPC flow — tokens are short-lived (300 seconds) and refreshed automatically.

---

## What you can ask Claude

Once installed, Claude has 57 tools to work with your Contabo account:

| Category | Examples |
|---|---|
| **Instances** | list / create / cancel / restart / shutdown / reinstall / rescue / get details |
| **DNS** | list zones / create / update / delete records, register domains |
| **Snapshots** | create / list / restore / delete snapshots |
| **Tags** | create / assign / unassign tags across resources |
| **Object Storage** | create / list / delete buckets, stats |
| **Networks** | private networks: create / attach / detach / delete |
| **Secrets** | create / get / list / delete secret store entries |
| **Users** | create / list / get API users |
| **Domains** | list / check availability / register |
| **Images** | list / upload / delete custom images |
| **PTR records** | get / set reverse DNS |
| **Audit logs** | search across instances, snapshots, actions |

Natural language examples:
- *"Create a new Cloud VPS L in Germany with the latest Ubuntu image"*
- *"Snapshot my main server, name it 'before-migration', then run apt upgrade on it"*
- *"List every DNS zone I own and show me which ones have wildcard records"*
- *"What did I change on instance #12345 last week?"* (uses audit logs)

---

## Updating

Because the config uses `npx -y`, you always get the latest published version on every Claude Desktop restart. No manual updates needed.

---

## Local development

```bash
git clone https://github.com/SMOrchestra-ai/contabo-mcp.git
cd contabo-mcp
npm install
cp .env.example .env   # then fill in your CONTABO_* values
npm test
npm run dev            # hot-reload via tsx
```

The test suite (338 tests, ~17 seconds) mocks the Contabo API completely — no live calls, no credentials needed to run tests.

---

## Contributing

Issues and pull requests welcome. For students wiring this into their first MicroSaaS:
- The [Entrepreneurs Oasis MENA](https://entrepreneursoasis.me) training program covers this end-to-end
- Video walkthroughs on YouTube: [@MamounAlamouri](https://www.youtube.com/@MamounAlamouri)

---

## License

[MIT](LICENSE) — © 2026 SMOrchestra.ai / Mamoun Alamouri