gigahost-mcp

A tiny MCP server exposing the Gigahost API (https://api.gigahost.no/api/v0) to any MCP-compatible client (Claude Code/Desktop, Cursor, Windsurf, Cline, or your own).

The Gigahost API is uniform REST, so the whole surface (~150 endpoints: DNS zones/records, .no domains, servers, web hosting, BGP, DynDNS) is wrapped by a single passthrough tool rather than one tool per endpoint. The model drives paths directly.

Tool

gigahost_request(method, path, body=None, query=None, files=None)

• method — GET / POST / PUT / DELETE

• path — e.g. /dns/zones, /servers/123/reboot

• body — JSON body for POST/PUT

• query — querystring params

• files — {form_field: local_file_path} for multipart uploads (e.g. POST /webhosting/{id}/files/upload). When set, body is sent as multipart form fields instead of JSON.

Returns {"status": <http_status>, "data": <json|text>}, or {"error": ...} on a network/file failure.

This covers the full Gigahost REST surface: all JSON endpoints plus multipart file uploads. The only bound on what works is the API key's permission scope.

Endpoint reference: https://gigahost.no/en/api-dokumentasjon

Examples

Calls below are shown as the tool arguments the model produces.

List DNS zones:

{ "method": "GET", "path": "/dns/zones" }

Add an A record to zone 4040:

{
  "method": "POST",
  "path": "/dns/zones/4040/records",
  "body": { "record_name": "@", "record_type": "A", "record_value": "203.0.113.10", "record_ttl": 3600 }
}

Reboot a server:

{ "method": "GET", "path": "/servers/123/reboot" }

Upload a file to a web-hosting account (multipart):

{
  "method": "POST",
  "path": "/webhosting/55/files/upload",
  "files": { "file": "/local/path/index.html" }
}

Related MCP server: panelica-mcp

Prerequisites

• Python 3.11+

• A Gigahost API key (flux_live_<hex>), created in the Flux dashboard under Konto → API keys. Scope it to only the permissions you need (e.g. DNS / domain). It is revocable and shown only once at creation.

• The key is read from the GIGAHOST_API_KEY environment variable.

Install

Pick whichever you already use.

Option A — uv (zero install)

Dependencies are declared inline (PEP 723), so nothing to install:

GIGAHOST_API_KEY=flux_live_xxxxxxxx uv run /path/to/server.py

Option B — pip / venv

python -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
GIGAHOST_API_KEY=flux_live_xxxxxxxx python server.py

Self-check (offline, no key, no network)

uv run server.py --selfcheck      # or: python server.py --selfcheck
# prints: ok

Configure your MCP client

Most clients read a JSON config with an mcpServers map. Add one of the following, using an absolute path to server.py and your key in env.

With uv:

{
  "mcpServers": {
    "gigahost": {
      "command": "uv",
      "args": ["run", "/absolute/path/to/server.py"],
      "env": { "GIGAHOST_API_KEY": "flux_live_xxxxxxxx" }
    }
  }
}

With a venv / system Python:

{
  "mcpServers": {
    "gigahost": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"],
      "env": { "GIGAHOST_API_KEY": "flux_live_xxxxxxxx" }
    }
  }
}

Config file locations vary by client, e.g.:

• Claude Desktop — claude_desktop_config.json (Settings → Developer → Edit Config)

• Cursor — ~/.cursor/mcp.json

• Windsurf / Cline / others — their MCP settings JSON

Claude Code (CLI shortcut)

claude mcp add -s user gigahost -e GIGAHOST_API_KEY=flux_live_xxxxxxxx \
  -- uv run /absolute/path/to/server.py

After configuring, the client should list a gigahost server with the gigahost_request tool. Smoke-test by asking it to GET /dns/zones.

Key permissions (scope)

When you create the Flux API key you set an access level per area. This bounds what gigahost_request can do, independent of the code:

• Ingen — no access, calls return 403.

• Les — read only, GET works, writes (POST/PUT/DELETE) return 403.

• Les/skriv — full read + write.

Areas map to API path prefixes:

Three traps, all found by probing the live API rather than reading the docs:

403 is the catch-all. A bogus path returns the same "You do not have permission for this operation." as a genuine denial, so a 403 proves neither that the path exists nor that a scope is missing.

A key cannot audit itself. Every endpoint marked (admin only) needs a session token and always 403s to a key, including all of /account/apikeys. So the only way to know what a key can do is to look in the Flux web UI.

Scope does not gate everything. /account returns full account data even for a key scoped to dns alone, and /servers / /webhosting / /bgp return 200 with empty collections when you own none of those. Neither a 200 nor an empty list tells you a scope is granted. /my/invoices 403s under every scope tried, including after granting Fakturering, for reasons that cannot be resolved from the API. Read invoices in the Flux UI.

Grant the minimum each area needs, not blanket Les/skriv. But note that DNS og domener must be Les/skriv for POST /dns/domains/register, and must not be pinned to specific zone IDs, since a newly registered domain is by definition not in that list. See API.md for the full endpoint map.

Security

• The API key is read from GIGAHOST_API_KEY only. It is never written to this repo.

• Putting the key in a client config file (or ~/.claude.json via claude mcp add -e) stores it in plaintext. Acceptable for a personal scoped key on your own machine. Revoke and rotate in Flux if it leaks.

• Prefer a narrowly-scoped key over your account password.

License

MIT