infomaniak-mcp-agent

# infomaniak-mcp-agent

[![npm version](https://img.shields.io/npm/v/infomaniak-mcp-agent.svg)](https://www.npmjs.com/package/infomaniak-mcp-agent)
[![npm downloads](https://img.shields.io/npm/dm/infomaniak-mcp-agent.svg)](https://www.npmjs.com/package/infomaniak-mcp-agent)
[![CI](https://github.com/Mogacode-ma/infomaniak-mcp-agent/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Mogacode-ma/infomaniak-mcp-agent/actions/workflows/ci.yml)
[![CodeQL](https://github.com/Mogacode-ma/infomaniak-mcp-agent/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/Mogacode-ma/infomaniak-mcp-agent/actions/workflows/codeql.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D18-43853d.svg)](https://nodejs.org)
[![TypeScript strict](https://img.shields.io/badge/TypeScript-strict-3178c6.svg)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/Model_Context_Protocol-1.0-9333ea.svg)](https://modelcontextprotocol.io/)
[![Tools](https://img.shields.io/badge/tools-81-blueviolet.svg)](#tools)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)
[![GitHub stars](https://img.shields.io/github/stars/Mogacode-ma/infomaniak-mcp-agent?style=social)](https://github.com/Mogacode-ma/infomaniak-mcp-agent/stargazers)

> **Drive your entire [Infomaniak](https://www.infomaniak.com) account from [Claude](https://www.anthropic.com/claude) — agentic, two-phase commit, open-source.**

`infomaniak-mcp-agent` is an unofficial [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes the full surface of Infomaniak — Switzerland's sovereign cloud — as **81 tools** an LLM can call directly: web hosting, mail (kSuite), kDrive, domains, DNS, DNSSEC, FTP/SSH users, AI products, account audits and more. Every destructive operation goes through a strict two-phase commit, so an agent can never silently delete or mutate something on your account.

```
You → Claude:  "audit the example.com hosting and tell me which mailboxes are over quota"
Claude → MCP:  infomaniak_audit_account → infomaniak_list_mail_hostings → infomaniak_list_mailboxes
Claude → You:  3 mailboxes >85% — paul@ (94%), notify@ (88%), team@ (87%). Want me to add an alert?
```

## Table of contents

- [Why](#why-this-exists) · [What it does](#what-you-can-do-with-it) · [How it differs](#why-agentic-and-not-wrapper)
- [Install](#install) · [Authentication](#authentication) · [Quick example](#quick-example)
- [Tools](#tools) (81 across 13 areas) · [Limitations](#limitations) · [Roadmap](#roadmap) · [FAQ](#faq)
- [Contributing](#contributing) · [License](#license)

## Why this exists

Infomaniak is one of the very few **independent, Swiss-owned, open-source-friendly cloud providers** in Europe — running its own datacentres in Switzerland, on hydro and wind power, with no parent in the US or China. Its product range is huge (web hosting, mail, kDrive, kChat, DNS, AI cloud, Swiss Backup, …) but its API is split between a documented public surface and a private manager-only one — which means automating real workflows usually requires a browser session, custom scripts, or both.

This project closes that gap by exposing **everything** through a single MCP server, so Claude or any other MCP client can run real account operations through natural language: provision a hosting, rotate a DNS record, create a mailbox, audit your domains for upcoming expirations, browse your kDrive — without ever forcing you to leave the chat or write a script.

## 🎒 Built in the open, in real time, by vibe-coding

This project was built rapidly by an LLM driving a terminal session ("vibe-coding"), with live tests against a real Infomaniak account at every step. **It works perfectly on the maintainer's local setup** and the full pipeline is green (TypeScript strict, ESLint, Prettier, 37 tests, build, CodeQL, gitleaks).

That said — given how it was built and given that several endpoints used here are reverse-engineered (see [`REVERSE-ENGINEERING.md`](./REVERSE-ENGINEERING.md)) — **it is entirely possible that you'll hit (potentially big) bugs** depending on your account topology, plan tier, scopes, or Infomaniak's own changes. We are here to fix them as they show up. Please:

1. Open an issue with the exact tool call, the input, the response, and your environment (Node version, OS, MCP client). Sanitize tokens / cookies / customer names before pasting.
2. Or, even better, send a PR with a failing test and we will work from there together.

We move fast and ship often. Don't be shy.

## ⚠️ Status: unofficial

This project is **not affiliated with, endorsed by, or sponsored by Infomaniak Network SA**. It is a community-driven tool that combines:

1. The **public Infomaniak API** ([api.infomaniak.com](https://developer.infomaniak.com/)), used with a Bearer token you generate yourself.
2. **Reverse-engineered manager endpoints** ([manager.infomaniak.com/proxy/...](https://manager.infomaniak.com/)), required for write operations on web hosting that the public API silently ignores.

For full transparency, read [`REVERSE-ENGINEERING.md`](./REVERSE-ENGINEERING.md). Infomaniak may change these endpoints without notice; we do our best to keep up but cannot guarantee long-term compatibility.

## What you can do with it

Once installed, you can ask Claude things like:

- *"List every domain on my account that expires in less than 60 days, sorted by date."*
- *"Create a new site `staging.example.com` on hosting `WP1234567`, PHP 8.3, root in `/sites/staging`."*
- *"Add a TXT record on `example.com` for the new Postmark DKIM, then verify it resolves."*
- *"How much disk does the database `myprefix_wp123456` use, and which application is wired to it?"*
- *"Create a mailbox `hello@example.com` with a 16-character random password and forward it to my Gmail."*
- *"Show me which kDrives I'm an admin on and how full they are."*
- *"Audit my whole account: any locked product, expiring SSL, broken DNSSEC, ongoing operations?"*
- *"Undo the last DNS change I made through this session."*

It will not silently mutate anything destructive: every change goes through a *plan + confirmation token* round-trip. You stay in control even if the model gets creative.

## Why "agentic" and not "wrapper"

Most MCP servers expose one tool per HTTP endpoint and call it a day. This one is built differently:

- **Guided dialogues** — creating a site walks you through "which organization? which hosting? root domain or subdomain? what type? recap?" instead of asking you to know the right tool to call upfront.
- **Two-phase commit** — every destructive operation returns a *plan* with a single-use confirmation token (60 s TTL). Nothing is mutated until you call back with the token.
- **Pre-flight checks** — the server checks for conflicts (existing FQDN, busy hosting, expired domain) *before* hitting the API.
- **Actionable errors** — every error tells you what happened, why, and the next step you can take.
- **Introspection** — `infomaniak_overview`, `infomaniak_help` and `infomaniak_explain` give the agent context-on-demand instead of forcing it to memorize a tool catalog.
- **Session memory** — `infomaniak_history` lists every destructive action of the current session, and `infomaniak_undo` reverses the ones that are reversible.

See [`ARCHITECTURE.md`](./ARCHITECTURE.md) for the full design rationale.

## Install

Available on npm — the recommended path is to let `npx` fetch the latest release on demand:

```bash
npx infomaniak-mcp-agent
```

(no install step needed; `npx` resolves the latest version on first invocation and caches it).

Or install globally if you prefer a stable binary in your `$PATH`:

```bash
npm install -g infomaniak-mcp-agent
```

If you'd rather pin to a specific commit (or hack on the source), install from this repo:

```bash
git clone https://github.com/Mogacode-ma/infomaniak-mcp-agent.git
cd infomaniak-mcp-agent
npm ci
npm run build
# resulting binary: ./dist/server.js
```

### Configure Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%AppData%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "infomaniak": {
      "command": "npx",
      "args": ["-y", "infomaniak-mcp-agent"],
      "env": {
        "INFOMANIAK_API_TOKEN": "paste-your-token-here",
        "INFOMANIAK_AUTH_MODE": "auto"
      }
    }
  }
}
```

Restart Claude Desktop to pick up the change.

### Configure Claude Code

```bash
claude mcp add infomaniak \
  -e INFOMANIAK_API_TOKEN=paste-your-token-here \
  -e INFOMANIAK_AUTH_MODE=auto \
  -- npx -y infomaniak-mcp-agent
```

## Authentication

Two distinct credentials are needed because Infomaniak runs two APIs side-by-side:

| API | Auth | Purpose |
|---|---|---|
| `api.infomaniak.com/{1,2}/...` | **Bearer token** | Read-mostly: profile, products, mail, drive, dns, domains, billing |
| `manager.infomaniak.com/proxy/...` | **SASESSION cookie + CSRF token** | Writes on web hosting (sites, databases, applications) |

### 1. Bearer token (required)

1. Sign in to your Infomaniak account.
2. Go to [manager.infomaniak.com/v3/ng/profile/user/token/list](https://manager.infomaniak.com/v3/ng/profile/user/token/list).
3. Click **"Create a token"**, give it a long lifetime, copy the value.
4. Set it in `INFOMANIAK_API_TOKEN`.

### 2. Manager session (auto, recommended)

The manager-private API does not accept Bearer tokens or OAuth (Infomaniak only exposes `openid profile email phone` scopes to third-party apps; `web`, `mail`, etc. are reserved). Instead, we read the `SASESSION` and `MANAGER-XSRF-TOKEN` cookies that **your local Chrome already has** when you are logged into [manager.infomaniak.com](https://manager.infomaniak.com).

With `INFOMANIAK_AUTH_MODE=auto` (the default), the MCP reads these cookies on demand using [`chrome-cookies-secure`](https://www.npm