IONOS CLOUD MCP Server

IONOS CLOUD MCP Server

This project implements a Model Context Protocol (MCP) server that allows LLMs to interact with IONOS CLOUD resources. The server is written in Go and uses the official IONOS CLOUD SDK.

What is MCP?

The Model Context Protocol (MCP) is an open standard that allows AI assistants to connect to external tools and data sources. It defines a JSON-RPC 2.0 interface over stdio (or HTTP) through which an LLM client can discover and invoke tools provided by a server. This MCP server exposes IONOS CLOUD infrastructure operations as tools, enabling AI assistants like Claude to list, inspect, and manage your cloud resources through natural language. It is designed for developers and platform engineers who want to interact with IONOS CLOUD programmatically through an AI-powered workflow.

Supported Products

Installation

Pick whichever fits your workflow.

Homebrew (macOS, Linux)

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

Docker (linux/amd64, linux/arm64)

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

Run with the MCP stdio transport:

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

go install

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

Pre-built binaries

Download the archive for your OS/arch from the latest release (Linux, macOS, Windows × amd64, arm64).

From source

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. Set the required environment variables:

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

# Optional: S3 credentials for Object Storage data-plane operations
# Only required if using Object Storage tools (list/inspect buckets, objects, access keys, etc.)
export IONOS_S3_ACCESS_KEY="your-s3-access-key"
export IONOS_S3_SECRET_KEY="your-s3-secret-key"

You can generate a token from the IONOS CLOUD DCD under Management > Token Management. S3 credentials for Object Storage can be created in the same interface under Object Storage > Access Keys.

Usage

The server uses stdio for communication following the MCP protocol. To run the server:

./ionoscloud-mcp

Integration with MCP Clients

To use this server with an MCP client (like Claude Desktop), add it to your MCP settings:

{
  "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"
      }
    }
  }
}

Note: IONOS_TOKEN is required. The Object Storage credentials are only needed if you plan to use Object Storage tools.

Optional: eager tool loading

By default, the server registers Compute and Object Storage tools lazily — clients must call ionos_load_compute_tools or ionos_load_objectstorage_tools first, after which the server emits notifications/tools/list_changed. Some MCP clients do not refresh their tool catalog on that notification, leaving the underlying tools undiscoverable.

Set IONOS_MCP_EAGER_LOAD=true (or 1, yes, on) to register every tool at startup instead. All tools then appear in the initial tools/list response.

{
  "mcpServers": {
    "ionoscloud": {
      "command": "/path/to/ionoscloud-mcp",
      "env": {
        "IONOS_TOKEN": "your-api-token",
        "IONOS_MCP_EAGER_LOAD": "true"
      }
    }
  }
}

Development

Testing the MCP Protocol

You can test the server's MCP protocol implementation using stdin/stdout:

# 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 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

make build
# or
go build -o ionoscloud-mcp .

Available Make Targets

• make build - Build the binary
• make test - Run tests
• make clean - Remove build artifacts
• make fmt - Format code
• make vet - Run go vet
• make check - Run fmt and vet
• make deps - Download and tidy dependencies

Dependencies

This project uses minimal external dependencies:

• ionos-cloud/sdk-go-bundle - IONOS CLOUD Go SDK Bundle

API Documentation

For more information about the IONOS CLOUD API, refer to:

• IONOS CLOUD API Documentation
• API Specifications
• SDK Documentation

License

Apache License 2.0 - See LICENSE file for details.