# Quick Start

This guide walks you through installing the MCP server, configuring your API credentials, and connecting it to Claude Desktop.

## Prerequisites

Before you begin, make sure you have:

* An <code class="expression">space.vars.ionos\_cloud</code> account with an API token
* A supported AI client. For more information, see [<mark style="color:blue;">Connect to an AI Client</mark>](/cloud/ai/mcp-server/connect-to-an-ai-client.md) for the 12 clients with dedicated setup guides (plus any other MCP-compatible client)

To generate an API token, log in to the [<mark style="color:blue;">DCD</mark>](https://dcd.ionos.com/) and go to **Management** > **Token Management**.

{% stepper %}
{% step %}

### Install the MCP server

**Option A: Download a pre-built binary (recommended)**

Download the latest binary for your platform from the [<mark style="color:blue;">GitHub Releases page</mark>](https://github.com/ionos-cloud/ionoscloud-mcp/releases):

| Platform              | File                               |
| --------------------- | ---------------------------------- |
| macOS (Apple Silicon) | `ionoscloud-mcp_darwin_arm64`      |
| macOS (Intel)         | `ionoscloud-mcp_darwin_amd64`      |
| Linux (x86-64)        | `ionoscloud-mcp_linux_amd64`       |
| Windows (x86-64)      | `ionoscloud-mcp_windows_amd64.exe` |

On macOS and Linux, make the binary executable and move it to a permanent location. Replace the filename with the one you downloaded from the table above:

```bash
chmod +x ionoscloud-mcp_<platform>_<arch>
mv ionoscloud-mcp_<platform>_<arch> /usr/local/bin/ionoscloud-mcp
```

For example, on Linux x86-64 use `ionoscloud-mcp_linux_amd64`; on macOS Intel use `ionoscloud-mcp_darwin_amd64`.

On Windows, rename the file to `ionoscloud-mcp.exe` and move it to a folder on your `PATH`, for example `C:\Users\you\bin\`. If you reference the binary by full path in the JSON config (as in the examples below), the folder does not need to be on `PATH`.

{% hint style="info" %}
**macOS Gatekeeper:** the released binary is currently unsigned. On first launch macOS may block it with *"cannot be verified"*. Remove the quarantine attribute once:

```bash
xattr -d com.apple.quarantine /usr/local/bin/ionoscloud-mcp
```

{% endhint %}

**Option B: Build from source**

If you prefer to build from source, you need Go 1.21 or later. Check your Go version:

```bash
go version
```

If the command is not found, download Go from [<mark style="color:blue;">go.dev/dl</mark>](https://go.dev/dl/).

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

{% endstep %}

{% step %}

### Add the MCP server to Claude Desktop

Open the Claude Desktop configuration file:

* **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` (`~` is shorthand for your home folder, for example `/Users/yourname`)
* **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` (paste `%APPDATA%\Claude` into File Explorer to open the folder)

If the file does not exist, create it with your text editor and paste the following as the entire file content:

```json
{
  "mcpServers": {
    "ionoscloud": {
      "command": "/usr/local/bin/ionoscloud-mcp",
      "env": {
        "IONOS_TOKEN": "your-api-token"
      }
    }
  }
}
```

Replace `your-api-token` with your <code class="expression">space.vars.ionos\_cloud\_api</code> token. By default, all tools are registered at startup; no extra env var is required. If you need to reduce the startup tool count (for example, on Windsurf), set `IONOS_MCP_LOAD_MODE=lazy`. For more information, see [<mark style="color:blue;">Selective Tool Loading</mark>](/cloud/ai/mcp-server/configuration/selective-tool-loading.md).

{% hint style="info" %}
**Using Object Storage?** Add `IONOS_S3_ACCESS_KEY` and `IONOS_S3_SECRET_KEY` to the `env` block as well. For more information, see [<mark style="color:blue;">Authentication</mark>](/cloud/ai/mcp-server/configuration/authentication.md).
{% endhint %}
{% endstep %}

{% step %}

### Restart Claude Desktop

Quit and reopen Claude Desktop. A hammer icon (🔨) appears in the input bar when MCP tools are available.
{% endstep %}

{% step %}

### Test the connection

In a new conversation, type:

> List my <code class="expression">space.vars.ionos\_cloud</code> data centers.

{% hint style="success" %}
**Result:** Claude calls the `list_datacenters` tool and returns your data centers with names, locations, and IDs.
{% endhint %}
{% endstep %}
{% endstepper %}

## Complete configuration reference

Three ready-to-use configurations for the most common setups:

**Token only, Compute Engine, Cloud DNS, Billing, Certificate Manager (default eager mode):**

```json
{
  "mcpServers": {
    "ionoscloud": {
      "command": "/usr/local/bin/ionoscloud-mcp",
      "env": {
        "IONOS_TOKEN": "your-api-token"
      }
    }
  }
}
```

**Token +** <code class="expression">space.vars.ionos\_cloud\_object\_storage</code> **credentials (default eager mode):**

```json
{
  "mcpServers": {
    "ionoscloud": {
      "command": "/usr/local/bin/ionoscloud-mcp",
      "env": {
        "IONOS_TOKEN": "your-api-token",
        "IONOS_S3_ACCESS_KEY": "your-access-key",
        "IONOS_S3_SECRET_KEY": "your-secret-key"
      }
    }
  }
}
```

**Token only, lazy mode (advanced — for Windsurf or cost-conscious clients):**

```json
{
  "mcpServers": {
    "ionoscloud": {
      "command": "/usr/local/bin/ionoscloud-mcp",
      "env": {
        "IONOS_TOKEN": "your-api-token",
        "IONOS_MCP_LOAD_MODE": "lazy"
      }
    }
  }
}
```

## Next steps

* [<mark style="color:blue;">Connect to other AI clients</mark>](/cloud/ai/mcp-server/connect-to-an-ai-client.md)
* [<mark style="color:blue;">Configure Object Storage credentials</mark>](/cloud/ai/mcp-server/configuration/authentication.md)
* [<mark style="color:blue;">Browse the full tool list</mark>](/cloud/ai/mcp-server/tool-reference.md)
* **Add the** <code class="expression">space.vars.ionos\_cloud</code> **Documentation MCP:** the docs site at `https://docs.ionos.com/cloud/~gitbook/mcp` is a free companion MCP server that gives your AI assistant access to all <code class="expression">space.vars.ionos\_cloud</code> product documentation alongside your live account data. Add it to your `mcpServers` config with a `url` key (no credentials required). For more information, see [<mark style="color:blue;">IONOS CLOUD Documentation MCP</mark>](/cloud/ai/mcp-server/overview.md#ionos-cloud-documentation-mcp).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ionos.com/cloud/ai/mcp-server/quick-start.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.