ionoscloud-mcp

# IONOS CLOUD MCP Server

![Official IONOS Cloud](https://img.shields.io/badge/IONOS%20Cloud-Official-00BFFF.svg)
[![Apache 2.0](https://img.shields.io/github/license/ionos-cloud/ionoscloud-mcp)](LICENSE)
[![Go reference](https://pkg.go.dev/badge/github.com/ionos-cloud/ionoscloud-mcp.svg)](https://pkg.go.dev/github.com/ionos-cloud/ionoscloud-mcp)

A **read-only-by-default** [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that connects your IONOS CLOUD account to any MCP-compatible AI assistant or autonomous AI agent: Claude Desktop, Cursor, VS Code (GitHub Copilot), Windsurf, Cline, Continue, OpenCode, and 5+ others. **118 read-only tools across 7 IONOS CLOUD products** — list, inspect, and audit your infrastructure through natural-language prompts or programmatic agentic loops. Write operations across Compute (servers, volumes, networking, load balancing) and Managed Kubernetes (clusters, node pools, nodes) are strictly opt-in and create real, billable resources — see [Write operations](#write-operations).

Built and maintained by the IONOS Cloud team. The server runs as a local binary on your workstation, a CI runner, or inside a container. IONOS CLOUD API calls go directly to IONOS over HTTPS; no third-party AI provider sits in the data path.

**Compatibility:** MCP spec 2024-11-05 · Go 1.25+ for builds · OCI images for linux/amd64 and linux/arm64.

> 📚 **Full product documentation, per-client setup guides, FAQ, and tutorials:** [docs.ionos.com/cloud/ai/mcp-server](https://docs.ionos.com/cloud/ai/mcp-server)

**Get started in 60 seconds** (macOS or Linux, via Homebrew):

```bash
brew install ionos-cloud/ionos-cloud/ionoscloud-mcp
```

For other install paths (Docker, pre-built binary, `go install`, source), see [Installation](#installation).

<p align="center">
<a href="#why">Why</a> •
<a href="#registries--directories">Registries</a> •
<a href="#supported-products">Products</a> •
<a href="#installation">Install</a> •
<a href="#configuration">Config</a> •
<a href="#tool-loading-mode">Tool loading</a> •
<a href="#wire-transport">Transport</a> •
<a href="#write-operations">Write ops</a> •
<a href="#demo">Demo</a> •
<a href="#development">Dev</a> •
<a href="#related-projects">Related</a> •
<a href="#changelog">Changelog</a>
</p>

## Why

* **Read-only by default, writes strictly opt-in** — out of the box every tool is an inspection operation (`list_*`, `get_*`, `head_*`), so it's safe to connect to production accounts and to deploy inside unattended agent loops on CI runners. Write tools (`create_*`, `update_*`, `delete_*`) register only when you set `IONOS_MCP_TOOL_SCOPE`, and even then every create and delete requires a two-phase confirmation (preview → one-time token → execute). See [Write operations](#write-operations).
* **Local binary, no proxy** — IONOS CLOUD API calls go directly from your machine to IONOS Cloud. No third-party AI vendor in the data path.
* **EU-sovereign option** — pair the server with the [IONOS CLOUD AI Model Hub](https://docs.ionos.com/cloud/ai/ai-model-hub) and both the API calls *and* the LLM inference terminate inside IONOS's German data centres. See the [Fully Sovereign AI Workflow](https://docs.ionos.com/cloud/ai/mcp-server/use-cases/sovereign-ai-workflow) guide.
* **Open source** — Apache 2.0. Read the source, audit the behaviour, contribute, or fork.

## Registries & Directories

This server is published across multiple MCP registries and IDE marketplaces:

| Registry | Link |
|----------|------|
| Official MCP Registry | [io.github.ionos-cloud/ionoscloud-mcp](https://registry.modelcontextprotocol.io/v0/servers?cursor=io.github.ionos-cloud) |
| Smithery | [ionos-cloud/ionoscloud-mcp](https://smithery.ai/servers/ionos-cloud/ionoscloud-mcp) |
| mcp.so | [ionos-cloud-mcp-server](https://mcp.so/server/ionos-cloud-mcp-server/ionos-cloud) |
| Glama | [ionoscloud-mcp](https://glama.ai/mcp/servers/ionos-cloud/ionoscloud-mcp) |
| Cursor | [ionoscloud-mcp](https://cursor.directory/plugins/ionoscloud-mcp) |
| mcpservers.org | [ionoscloud-mcp](https://mcpservers.org/servers/ionos-cloud/ionoscloud-mcp) |
| PulseMCP | [ionoscloud](https://www.pulsemcp.com/servers/ionoscloud) |
| MCPMarket | [ionos-cloud](https://mcpmarket.com/server/ionos-cloud) |
| punkpeye/awesome-mcp-servers | [ionos-cloud/ionoscloud-mcp](https://github.com/punkpeye/awesome-mcp-servers) |

## Supported products

Read tools are named `list_*`, `get_*` and `head_*`; the opt-in write tools are `create_*`, `update_*`, `delete_*` plus domain verbs such as `start_*` and `attach_*`. In the default `eager` mode all tools register at startup; `lazy` mode defers Compute and Object Storage behind loader tools; `dynamic` mode exposes only three search/describe/call meta-tools for clients with hard tool caps. See [Tool loading mode](#tool-loading-mode).

| Product | Tools | Capabilities |
|---|---|---|
| [Compute Engine](docs/compute/) | 50 + 69 write | Data centers, servers, volumes, NICs, LANs, firewall rules, IP blocks, load balancers (basic / network / application), NAT gateways, security groups, private cross-connects, snapshots, images, templates, locations, requests, contract |
| [Kubernetes](docs/k8s/) | 8 + 8 write | Clusters, node pools, nodes, available versions |
| [Object Storage](docs/objectstorage/) | 23 | Buckets, bucket configuration (CORS, encryption, lifecycle, policy, public access block, replication, tagging, versioning, Object Lock), objects, access keys, regions |
| [DNS](docs/dns/) | 14 | Zones, zone files, records, reverse records, secondary zones, DNSSEC, quota |
| [Billing](docs/billing/) | 15 | Profile, invoices, EVN (provisioning intervals), traffic, usage, utilization, product pricing catalog, FOCUS v1.3 spec |
| [Certificate Manager](docs/cert/) | 6 | Certificates, auto-certificates, providers |
| [Activity Log](docs/activitylog/) | 2 | Contracts, events |

**120 read-only tools** (118 product + 2 loader), plus **77 opt-in write tools** on Compute Engine and Kubernetes — see [Write operations](#write-operations). For per-tool input/output schemas, see the [per-product docs](docs/) or the full [Tool Reference](https://docs.ionos.com/cloud/ai/mcp-server/tool-reference) at docs.ionos.com.

## Installation

Pick whichever fits your workflow.

### Homebrew (macOS, Linux) — recommended

```bash
brew install ionos-cloud/ionos-cloud/ionoscloud-mcp
```

### Docker (linux/amd64, linux/arm64)

```bash
docker pull ghcr.io/ionos-cloud/ionoscloud-mcp:latest
```

Run with the MCP stdio transport (default):

```bash
docker run -i --rm \
  -e IONOS_TOKEN="$IONOS_TOKEN" \
  ghcr.io/ionos-cloud/ionoscloud-mcp
```

Or over HTTP (see [Wire transport](#wire-transport)):

```bash
docker run --rm -p 8080:8080 \
  -e IONOS_TOKEN="$IONOS_TOKEN" \
  ghcr.io/ionos-cloud/ionoscloud-mcp --transport http --http-addr :8080
```

### Smithery

```bash
npx -y @smithery/cli install @ionos-cloud/ionoscloud-mcp --client claude-desktop
```

Supported `--client` values: `claude-desktop`, `claude-code`, `cursor`, `vscode`, `windsurf`, `cline`, `continue`, `gemini-cli`, `kiro`, and others. See the [Smithery listing](https://smithery.ai/servers/ionos-cloud/ionoscloud-mcp) for the current list.

### Pre-built binary

Download the archive for your OS/arch from the [latest release](https://github.com/ionos-cloud/ionoscloud-mcp/releases/latest). Available for Linux, macOS, and Windows on both amd64 and arm64.

### `go install`

```bash
go install github.com/ionos-cloud/ionoscloud-mcp@latest
```

### From source

```bash
git clone https://github.com/ionos-cloud/ionoscloud-mcp.git
cd ionoscloud-mcp
make build
```

## Configuration

You need an IONOS CLOUD account with API credentials.

```bash
# Required: API token for control-plane APIs (Compute, DNS, Billing, Certificate Manager, Object Storage management)
export IONOS_TOKEN="your-api-token"

# Optional: only required if you use Object Storage data-plane tools
# (listing objects, reading bucket configuration, checking access keys).
export IONOS_S3_ACCESS_KEY="your-s3-access-key"
export IONOS_S3_SECRET_KEY="your-s3-secret-key"

# Optional: opt in to write operations (default: read-only). Values are hierarchical,
# so a single level suffices: "write" allows create/update; "destructive" also allows
# delete (it implies "write"). See "Write operations".
# export IONOS_MCP_TOOL_SCOPE="write"
```

Generate a token in the [IONOS CLOUD DCD](https://dcd.ionos.com/) under **Management → Token Management**. Object Storage credentials are created under **Storage & Backup → IONOS CLOUD Object Storage → Key management**.

For least-privilege token scoping, see [Authentication](https://docs.ionos.com/cloud/ai/mcp-server/configuration/authentication) at docs.ionos.com.

### Integrating with an MCP client (manual)

Add the server to your AI client's MCP config:

```json
{
  "mcpServers": {
    "ionoscloud": {
      "command": "/path/to/ionoscloud-mcp",
      "env": {
        "IONOS_TOKEN": "your-api-token",
        "IONOS_S3_ACCESS_KEY": "your-s3-access-key",
        "IONOS_S3_SECRET_KEY": "your-s3-secret-key"
      }
    }
  }
}
```

The Object Storage credentials are only needed if you plan to use Object Storage tools.

Per-client setup guides for the 12 supported AI clients: [Connect to an AI Client](https://docs.ionos.com/cloud/ai/mcp-server/connect-to-an-ai-client) at docs.ionos.com.

## Tool loading mode

The load mode selects how tools are exposed. Set it with either the `--load-mode` flag or the `IONOS_MCP_LOAD_MODE` environment variable; **the flag wins if both are set**, and otherwise the default is `eager`. Parsing is case-insensitive.

- **`eager`** (default): all tools register at startup. Recommended for Claude Code (which defers full schemas client-side via ToolSearch, paying ~1–3k tokens for names only) and the only working mode for clients that ignore `notifications/tools/list_changed` (Claude Desktop, claude.ai connectors, Claude in Chrome, Smithery scanner).

- **`lazy`