[](LICENSE)
[](https://pkg.go.dev/github.com/ionos-cloud/ionoscloud-mcp)
# IONOS CLOUD MCP Server
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), Managed Kubernetes (clusters, node pools, nodes), DNS (zones, records, reverse records, DNSSEC) and Certificate Manager (certificates, auto-certificates, providers) 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).
Why โข
Registries โข
Products โข
Install โข
Config โข
Tool loading โข
Transport โข
Write ops โข
Demo โข
Dev โข
Related โข
Changelog
## 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 + 70 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 + 16 write | Zones, zone files (+ BIND import), records, reverse records, secondary zones (+ zone transfer), 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 + 8 write | Certificates, auto-certificates, providers |
| [Activity Log](docs/activitylog/) | 2 | Contracts, events |
**118 read-only tools**, plus **102 opt-in write tools** on Compute Engine, Kubernetes, DNS and Certificate Manager โ 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`**: Compute and Object Storage register only on demand. Two sentinel tools (`ionos_load_compute_tools`, `ionos_load_objectstorage_tools`) appear at startup; calling either registers the full product set and emits `notifications/tools/list_changed`. Use only if your MCP client honours that notification AND lacks client-side schema deferral โ otherwise eager mode is cheaper.
- **`dynamic`** (alias: `search`): the server exposes only **three** meta-tools โ `ionos_search_tools`, `ionos_describe_tools` and `ionos_call_tool` โ and the model discovers and invokes the full catalogue through them at runtime. The real tool list never changes, so unlike `lazy` this needs no `notifications/tools/list_changed` support. Intended for clients with **hard tool caps and no tool search of their own** (e.g. Cursor's ~40-tool cap, Windsurf's 100). Trade-off: the model must `search` โ `describe` โ `call` rather than seeing tools directly, costing extra round-trips, so prefer `eager` on Claude Code.
The server logs the effective mode and its source (flag / env / default) to stderr at startup, e.g. `load mode: dynamic (source: --load-mode flag)`.
```json
{
"mcpServers": {
"ionoscloud": {
"command": "/path/to/ionoscloud-mcp",
"args": ["--load-mode", "dynamic"],
"env": {
"IONOS_TOKEN": "your-api-token"
}
}
}
}
```
**Tool-count limits:** Windsurf caps connected MCP servers at 100 tools combined; Cursor caps at ~40 across all servers. With the default eager mode the server exceeds both. On Windsurf, `lazy` keeps the startup surface small enough; on Cursor (or any cap-limited client without its own tool search), use `dynamic` to present just three tools. For more information, see [Selective Tool Loading](https://docs.ionos.com/cloud/ai/mcp-server/configuration/selective-tool-loading).
## Wire transport
The server speaks stdio by default โ the mode every subprocess-spawning MCP client expects (Claude Desktop, Claude Code, Cursor, Windsurf, etc.). For remote or networked deployments (e.g. running the server centrally and pointing multiple clients at it), switch to the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) with `--transport http` or `IONOS_MCP_TRANSPORT=http`; **the flag wins if both are set**.
```bash
./ionoscloud-mcp --transport http --http-addr :8080
```
- `--transport ` (or `IONOS_MCP_TRANSPORT`) โ selects the transport. Unrecognised values fall back to `stdio` with a warning.
- `--http-addr ` (or `IONOS_MCP_HTTP_ADDR`) โ listen address for the HTTP transport. Default `127.0.0.1:8080` (local-only); use `:8080` to listen on all interfaces. Ignored for stdio.
The server logs the effective transport and its source to stderr at startup, e.g. `transport: http (source: --transport flag)`.
In HTTP mode, point your MCP client at `http://:/` as a Streamable HTTP server. There is no built-in TLS or authentication for the HTTP endpoint itself โ put it behind a reverse proxy (e.g. nginx, Caddy) if it needs to be reachable outside a trusted network. `IONOS_TOKEN` and the other IONOS CLOUD credentials still authenticate the server's own calls to the IONOS API regardless of transport.
## Write operations
**The server is read-only until you opt in.** Write tools are never registered and never appear in `tools/list` unless you set the `IONOS_MCP_TOOL_SCOPE` environment variable. The gate applies in every load mode, including the `dynamic` dispatcher โ there is no bypass.
Scope is a comma-separated, hierarchical set of capabilities (`read` is always on):
| `IONOS_MCP_TOOL_SCOPE` | Enables |
|--------------------------|------------------------------------------------|
| unset / `read` (default) | read-only (`list_*`, `get_*`, `head_*`) |
| `write` | the above **+** `create_*`, `update_*`, and the non-disruptive actions `start_`, `resume_`, `attach_`, `assign_` |
| `destructive` | the above **+** `delete_*` and the disruptive actions `stop_`, `reboot_`, `suspend_`, `upgrade_`, `restore_`, `detach_`, `recreate_`, `import_` (implies `write`) |
Unrecognised values fall back to read-only, and the effective scope is logged to stderr at startup. Because the levels are hierarchical, a single value is enough โ `destructive` alone already grants `write` and `read`; you don't need to list them all (though a comma-separated list like `read,write` is also accepted).
### What can be written
| Area | Resources |
|------|-----------|
| Compute | data centers, servers (+ start/stop/reboot/suspend/resume/upgrade), volumes (+ snapshot & restore, attach/detach), NICs, LANs |
| Networking | IP blocks (reserve, rename and release), security groups + rules, firewall rules, private cross connects |
| Load balancing | classic, network and application load balancers + forwarding rules, target groups, NAT gateways + rules |
| Images | snapshot and image update/delete |
| Kubernetes | clusters, node pools (scale, upgrade, autoscaling, LANs, labels, annotations, taints), single nodes (recreate, delete) |
| DNS | primary zones (+ BIND zone-file import), records, secondary zones (+ zone transfer), reverse records, DNSSEC enable/disable |
| Certificate Manager | auto-certificates, ACME providers, certificate rename/delete โ renames only change the name, the rest is immutable. Uploading certificate material is deliberately **not** offered: it would require passing a private key as a tool argument. |
102 tools in total. The server exposes 118 at the default read-only scope, 181 with `write`, and 220 with `destructive`. Reads are unaffected and always available.
**Two-phase confirmation.** Every `create_*` and `delete_*`, plus the disruptive actions (`stop_`, `reboot_`, `suspend_`, `upgrade_`, `restore_`, `detach_`, `recreate_`), is confirmation-gated, along with the DNS zone-file import. The first call performs no mutation: it returns a preview โ for a delete, a blast-radius summary of what will be destroyed โ plus a single-use `confirmation_token` (5-minute TTL, bound to that exact target and operation). Only a second call carrying that token executes. This keeps a human in the loop and limits the agent to one resource per call. Reversible single-field changes (`update_*`, `start_`, `attach_`, `assign_`) are a single call.
**Annotations.** Write tools carry MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`) so clients can build their own approval UX โ but enforcement is always server-side. Note that the class comes from the operation, not the HTTP verb: `stop_server` is a `POST` that is destructive, and `import_dns_zone_file` is a `PUT` that replaces every record in a zone.
---
> ## โ ๏ธ Write operations create real resources and real charges
>
> **Enabling `IONOS_MCP_TOOL_SCOPE` lets an AI model provision billable infrastructure in your live IONOS CLOUD account.** Every create is a real resource on a real invoice, effective immediately.
>
> Some resources cost money even when nothing is using them โ a reserved IP block, a snapshot, or a volume left behind after its server was deleted. Deletions are equally real: destroyed data is not recoverable without a snapshot, and a released IP address cannot be asked for again.
>
> **An AI model decides when and how often to call these tools.** It can misread your intent, retry more than you expected, or pick a larger resource than you had in mind. The two-phase confirmation exists to put a human in that loop, but it cannot stop a client configured to approve tool calls automatically โ in that setup the model can complete both phases on its own.
>
> **You are responsible for everything created, modified or deleted in your account through these tools, and for the resulting charges.** IONOS does not control and is not responsible for how a model chooses to call them, or for any cost, data loss or outage arising from those calls.
>
> Reduce the risk: leave the server read-only unless you need writes; grant `write` rather than `destructive` when deletion isn't required; require manual approval of tool calls in your client; read the preview before returning a confirmation token; and prefer a non-production account when experimenting.
---
Enable writes in your MCP client config, for example:
```json
{
"mcpServers": {
"ionoscloud": {
"command": "/path/to/ionoscloud-mcp",
"env": {
"IONOS_TOKEN": "your-api-token",
"IONOS_MCP_TOOL_SCOPE": "destructive"
}
}
}
}
```
## Demo
In Claude Desktop or any other supported client, after configuring the server, try one of these prompts. They cover the kinds of multi-step inspection workflows that are tedious to write as scripts but easy in natural language:
- **Cost audit:** *"Audit my IONOS CLOUD account, find the top 5 cost-inducing resources this month, and suggest cost-efficiency tips."*
- **Security sweep:** *"List every bucket whose public access block is off or whose policy is public โ flag anything that looks unintentional."*
- **Audit trail:** *"Show me every failed API request on my contract in the last 30 days, grouped by user."*
- **Forgotten resources:** *"Find unattached volumes, unused IP blocks, and stopped servers across all my data centers."*
- **DNS sanity check:** *"List all zones on my account and flag any without DNSSEC enabled or with records pointing to IPs I no longer own."*
- **Certificate expiry:** *"Which certificates on my account expire in the next 60 days?"*
- **Traffic spike investigation:** *"My last invoice was higher than usual โ show me daily traffic and utilization for the previous billing period and tell me what changed."*
- **Onboarding tour:** *"Walk me through what I have running on IONOS CLOUD โ datacenters, servers, storage, DNS โ like you're explaining it to a new teammate."*
Each prompt chains multiple `list_*` and `get_*` calls and produces a summary you can paste into a ticket, dashboard, or doc. For end-to-end walkthroughs:
* [Run a security posture audit on your IONOS CLOUD Object Storage buckets](https://docs.ionos.com/cloud/tutorials/ai/mcp-server/object-storage-security-audit)
* [Generate a FOCUS-compliant cost report](https://docs.ionos.com/cloud/tutorials/ai/mcp-server/focus-billing-finops)
## Development
### Testing the MCP protocol locally
You can test the server's MCP protocol implementation using stdin/stdout:
```bash
# Initialize and list tools
{
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1.0"}}}'
echo '{"jsonrpc":"2.0","method":"notifications/initialized"}'
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
sleep 1
} | ./ionoscloud-mcp
# Call a tool (requires a valid IONOS_TOKEN)
{
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1.0"}}}'
echo '{"jsonrpc":"2.0","method":"notifications/initialized"}'
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_datacenters","arguments":{}}}'
sleep 1
} | ./ionoscloud-mcp
```
### Building from source
```bash
make build
# or
go build -o ionoscloud-mcp .
```
Run `make` with no arguments to see the available targets.
## Related projects
* [IONOS CLOUD MCP Server product docs](https://docs.ionos.com/cloud/ai/mcp-server) โ full product documentation
* [IONOS CLOUD AI Model Hub](https://docs.ionos.com/cloud/ai/ai-model-hub) โ open-weight LLMs hosted in Germany; pair with this server for a fully EU-sovereign AI loop
* [IONOS CLOUD Documentation MCP](https://docs.ionos.com/cloud/~gitbook/mcp) โ a free public MCP server exposing the IONOS docs site for AI assistants
## Contributing
Issues and pull requests are welcome. For development setup, code style, and testing instructions, see [CONTRIBUTING.md](CONTRIBUTING.md). For questions and discussion, use [GitHub Discussions](https://github.com/ionos-cloud/ionoscloud-mcp/discussions).
## Security
If you believe you have found a security vulnerability, **please do not open a public issue**. Report it privately via GitHub's [private vulnerability reporting](https://github.com/ionos-cloud/ionoscloud-mcp/security/advisories/new) or by email to `sdk-tooling@ionos.com`. Full policy: [SECURITY.md](SECURITY.md).
## Changelog
Notable changes per release are tracked in [CHANGELOG.md](CHANGELOG.md). For the artefacts published with each tag (Linux/macOS/Windows binaries, multi-arch OCI images), see the [GitHub Releases](https://github.com/ionos-cloud/ionoscloud-mcp/releases) page.
## API documentation
For more information about the IONOS CLOUD API:
* [IONOS CLOUD API Documentation](https://api.ionos.com/docs/)
* [API specifications](https://github.com/ionos-cloud/rest-api/tree/main/public)
* [SDK documentation](https://github.com/ionos-cloud/sdk-go-bundle)
## License
Apache License 2.0 โ see [LICENSE](LICENSE).