Skip to main content
Glama

Domeneshop MCP

An open-source Model Context Protocol server for Domeneshop. Use domain names instead of remembering IDs, preview DNS changes, then apply with conflict detection, backups and independent readback.

Status: 76 automated tests and live read/preview tests through stdio, Docker and LiteLLM have passed. Keycloak group reconciliation, restricted tool access, credential revocation and gateway OAuth/refresh have been tested. End-to-end client acceptance and real API writes remain separate checks. No production DNS was changed during validation.

Intended use

Use Open WebUI as the frontend, LiteLLM as the MCP gateway and access-control point, and Keycloak for SSO. ChatGPT Work is a second client of the same gateway, so users can use Domeneshop directly from Work without opening Open WebUI. Both clients must receive only the server and tool permissions granted to their authenticated user.

Keycloak login alone does not grant Domeneshop access. The optional group reconciler maps staff-internal (Senior) to all 27 tools, with a separate reader policy available. Clients use personal gateway OAuth; the upstream credential stays private. Optional lifecycle revocation removes a deleted or disabled linked person's gateway identity and keys.

See client architecture, SSO and access policy for the two client flows, group mapping, authentication requirements and rollout checks. The reconciliation deployment guide covers setup and revocation limits.

Related MCP server: OrgSuite GoDaddy MCP

Features

  • All 15 operations documented in Domeneshop API v0: domains, DNS CRUD, HTTP forwards CRUD, invoices and dynamic DNS, including multiple hostnames and IPv4/IPv6 addresses.

  • DNS types: A, AAAA, CNAME, MX, SRV, TLSA, TXT, plus ANAME, CAA, DS and NS from Domeneshop's official Python client's type catalog. The latter four need real-account acceptance.

  • Shortcuts: website setup, verification TXT, exact IP replacement across selected domains, additive DNS copy/import, export, backup restore, configuration checks and expiry overview.

  • Local stdio and authenticated Streamable HTTP at /mcp for a central gateway.

  • Typed inputs, TLS verification, bounded read retries, domain allowlisting and read-only default.

The upstream API does not offer domain purchase/transfer, nameserver changes, mailbox administration, invoice payment or webhosting administration. This server cannot add those capabilities. API coverage and sources.

Install

Python 3.11+ (tested on 3.12). From the project directory:

python -m venv .venv
# Linux/macOS:
. .venv/bin/activate
# Windows PowerShell instead:
# .\.venv\Scripts\Activate.ps1
python -m pip install -e '.[dev]'

Obtain a token/secret from Domeneshop's API settings. Inject credentials through your process environment or a secret manager. Never commit them or paste them into chat. .env files are deliberately not loaded automatically.

Environment variable

Purpose / default

DOMENESHOP_TOKEN

Required upstream API token

DOMENESHOP_SECRET

Required upstream API secret

DOMENESHOP_ALLOW_WRITES

false; set exactly true to enable apply_plan

DOMENESHOP_ALLOWED_DOMAINS

Optional comma-separated exact domain names; omitted = all

DOMENESHOP_STATE_DIR

Backups/receipts, default ~/.domeneshop-mcp

MCP_HTTP_TOKEN

Required for HTTP; separate random secret, at least 32 characters

MCP_ALLOWED_HOSTS

HTTP Host allowlist; local hosts by default; explicit for non-loopback binds

MCP_ALLOWED_ORIGINS

Optional exact HTTP Origin allowlist; local origins by default

Domain allowlisting also disables invoices because invoices are account-wide. All HTTP callers with the same bearer credential share one upstream account and plans. This is a server for one trusted operator/team, not tenant isolation or per-user authorization. Run separate instances and credentials for separate trust boundaries.

Local stdio

domeneshop-mcp

Point your MCP client at the installed domeneshop-mcp executable (or the virtual environment's Python with arguments -m domeneshop_mcp.server). Inherit/inject the environment above. Use an absolute executable path when the client does not inherit your activated virtual environment. Protocol messages use stdout; application transport logging must stay on stderr.

Central HTTP / LiteLLM gateway

domeneshop-mcp --transport http --host 127.0.0.1 --port 8000

The MCP endpoint is http://127.0.0.1:8000/mcp with header Authorization: Bearer <MCP_HTTP_TOKEN>. For remote access, terminate valid HTTPS at your reverse proxy and set MCP_ALLOWED_HOSTS to its actual hostname (include port when applicable). Do not expose plain HTTP to the internet. Forward the bearer header and configure the gateway to send it. OAuth-only clients need an authenticating gateway: this server does not provide OAuth.

Use one worker/process: preview plans and their lock are in memory. Plans expire after ten minutes and disappear on restart. A shared backup directory does not make multiple workers safe. TLS to Domeneshop is always verified; redirects and environment-supplied HTTP proxies are disabled.

See deployment examples for Docker and a systemd unit. These are templates; they do not install, publish or change your gateway automatically.

Typical workflows

  1. list_domains, list_dns_records and list_forwards inspect current state.

  2. Call setup_website, add_verification_txt, plan_dns_batch or a CRUD tool to get a preview.

  3. Inspect actions, before, after, warnings and expiry. The caller must have user authorization.

  4. Call apply_plan(plan_id) to execute. Check its returned status.

  5. get_plan retrieves the result; export_zone reads fresh state.

Example natural-language requests:

  • «Vis domener som utløper de neste 30 dagene.»

  • «Forbered example.no med 192.0.2.10 og www som CNAME.»

  • «Legg til denne verifiserings-TXT-en uten å erstatte SPF.»

  • «Vis hvilke poster som endres når 192.0.2.10 byttes til 192.0.2.20 på disse domenene.»

ensure_dns_records only adds missing exact records by default. With replace_rrsets=true, all existing records of each supplied host/type are replaced by the supplied set. Other sets are preserved. setup_website uses that replacement mode, preserves an omitted IP family, and stops for conflicting aliases/forwards. It does not provision hosting or certificates.

What a write result means

Status

Meaning

verified

All planned operations passed independent API readback and state checks

accepted_unverified

Upstream accepted DDNS but intended address was not proven

partial_or_unknown

An operation or readback failed; some writes may have happened

Backups are written before the first mutation; an unwritable state directory blocks writes. Each successful operation is read back. The server checks for state drift before and between operations. The upstream API has no conditional-write/version contract, so there remains a race between a preflight read and a write. Batch operations are not transactions. On failure, execution stops; there is no blind retry or automatic rollback. Inspect current state before preparing a new plan. restore_dns_backup previews DNS restoration; forwards must be restored explicitly.

The plan ID is not a human-approval mechanism. Your MCP client/gateway is responsible for deciding whether the user authorized an operation. Verified API state does not prove public DNS propagation, website availability or email delivery. Automatic-IP DDNS uses the server's egress IP.

Backups contain DNS/TXT data and should be private. On POSIX they use restrictive permissions; on Windows protect the state directory with the service account's ACL. Backups are retained until the operator removes them. Routine logs omit API payloads and credentials; do not enable HTTP debug logging around a credentialed deployment.

Development

python -m pytest -q
python -m ruff check .
python -m ruff format --check .

The official MCP Python SDK is pinned to its maintained 1.x line (>=1.28,<2) to keep the FastMCP API stable. Upgrade to 2.x as an explicit compatibility change with protocol tests. Runtime dependencies are pinned in requirements.lock; see deployment instructions for using it. CI checks Linux/Windows and supported Python versions. Contributing.

License

MIT for this project's code. Domeneshop is a third-party service; this is an independent project, not an official Domeneshop product. docs/domeneshop-openapi.json is a reference snapshot of Domeneshop's public API specification; upstream attribution/terms remain applicable.

Available Tools

27 tools
account_overviewB
Read-onlyIdempotent

Summarize domain counts, statuses and domains expiring within the chosen period.

Inputs: expiry_days. Returns: object

add_verification_txtB
Read-only

Preview adding a TXT verification token without replacing existing TXT/SPF records.

Inputs: value (required), domain (required), ttl, host. Returns: object

apply_planA
Destructive

Execute an authorized preview before it expires. Backs up state, rejects drift, verifies writes by readback and stops on failure. Never automatically replays writes. A multi-operation plan is not atomic. Check returned status, not just tool success.

Inputs: plan_id (required). Returns: object

audit_dnsA
Read-onlyIdempotent

Inspect configuration for duplicate records, CNAME collisions, multiple SPF and DMARC. This is a bounded configuration check, not a complete email or DNS security audit.

Inputs: domain (required). Returns: object

copy_dns_recordsA
Read-only

Preview copying DNS to another domain, optionally selected hosts. Adds only; skips exact duplicates; keeps absolute target names unchanged.

Inputs: source_domain (required), target_domain (required), hosts. Returns: object

create_dns_recordA
Read-only

Preview adding one record. Identical records are a no-op; use apply_plan to write.

Inputs: domain (required), record (required). Returns: object

create_forwardB
Read-only

Preview a new HTTP forward with DNS collision checks.

Inputs: domain (required), forward (required). Returns: object

delete_dns_recordB
Read-only

Preview deletion of an exact DNS record; shows its current contents.

Inputs: domain (required), record_id (required). Returns: object

delete_forwardC
Read-only

Preview deletion of a specific HTTP forward.

Inputs: host (required), domain (required). Returns: object

ensure_dns_recordsC
Read-only

Preview idempotent DNS setup/import. By default only adds missing exact records. replace_rrsets=true replaces ALL records of each supplied host/type; other sets stay.

Inputs: domain (required), records (required), replace_rrsets. Returns: object

export_zoneB
Read-onlyIdempotent

Export a complete JSON snapshot of DNS and forwards; no filesystem write.

Inputs: domain (required). Returns: object

get_dns_recordC
Read-onlyIdempotent

Read the exact DNS record ID within a domain.

Inputs: domain (required), record_id (required). Returns: object

get_domainB
Read-onlyIdempotent

Get domain registration, expiry, nameservers and enabled services.

Inputs: domain (required). Returns: object

get_forwardC
Read-onlyIdempotent

Get the forward for a relative host, e.g. www or @.

Inputs: host (required), domain (required). Returns: object

get_invoiceB
Read-onlyIdempotent

Get a single account invoice by invoice number.

Inputs: invoice_id (required). Returns: object

get_planB
Read-onlyIdempotent

Read a plan preview or the stored execution result in this process.

Inputs: plan_id (required). Returns: object

list_dns_recordsB
Read-onlyIdempotent

List DNS, optionally filtering relative host (e.g. @, www) and record type.

Inputs: domain (required), host, record_type. Returns: object

list_domainsA
Read-onlyIdempotent

List account domains; optional substring search. Returns deterministic count.

Inputs: query. Returns: object

list_forwardsC
Read-onlyIdempotent

List HTTP/WWW forwards for a domain.

Inputs: domain (required). Returns: object

list_invoicesA
Read-onlyIdempotent

List invoices from the past three years, optionally by payment status. Invoice URLs may grant access to invoice content; treat them as private.

Inputs: status. Returns: object

plan_dns_batchA
Read-only

Preview up to 100 ordered creates/updates/deletes. Batch execution is non-atomic.

Inputs: domain (required), changes (required). Returns: object

replace_ipB
Read-only

Preview replacing an exact A/AAAA address across explicitly selected domains. Includes matching mail hosts. Preserves TTL and all unrelated records.

Inputs: new_ip (required), old_ip (required), domains (required). Returns: object

restore_dns_backupA
Read-only

Preview restoring DNS content from this server's pre-change backup ID (= plan ID). Recreated records get new IDs. Forwards require separate explicit changes.

Inputs: domain (required), backup_id (required). Returns: object

setup_websiteB
Read-only

Preview apex A/AAAA and optional www CNAME. Replaces supplied host/type sets. An omitted address family is preserved. Conflicting www records require explicit resolution.

Inputs: domain (required), ttl, www, ipv4, +1 more. Returns: object

update_dns_recordB
Read-only

Preview replacing the full payload of a specific DNS record, preserving its ID.

Inputs: domain (required), record (required), record_id (required). Returns: object

update_dynamic_dnsA
Read-only

Preview DDNS for fully qualified hostnames. Omitted IP requires use_request_ip=true; that mode uses the server's egress IP and cannot verify the intended client IP.

Inputs: hostnames (required), ips, use_request_ip. Returns: object

update_forwardB
Read-only

Preview updating the existing forward at forward.host. Host cannot be renamed.

Inputs: domain (required), forward (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 27 tools

    Disambiguation4/5

    Most tools have clearly distinct targets (domains vs DNS records vs forwards vs invoices vs plans), and the preview/apply convention is applied consistently. However, several high-level DNS writers (ensure_dns_records, setup_website, replace_ip, copy_dns_records, add_verification_txt) overlap with the primitive create/update/delete_dns_record tools, so an agent must read carefully to choose the right one.

    Naming Consistency4/5

    Nearly all names follow a predictable snake_case verb_noun pattern (list_domains, create_dns_record, update_forward, apply_plan). The only real deviation is the noun-first account_overview, which is a minor cosmetic inconsistency.

    Tool Count3/5

    27 tools is heavy for a single server and sits above the comfortable 3-15 range. The scope is genuinely broad (domains, DNS, forwards, DDNS, invoices, backups, plan lifecycle), so most tools earn their place, but the count is borderline for what could be split.

    Completeness4/5

    Coverage is strong: full DNS record CRUD, forwards CRUD, DDNS, invoice retrieval, batch planning, zone export, audit, and backup/restore. The main gap is domain registration lifecycle (no create/delete/transfer/nameserver-set operations on the domain itself), but core DNS and account workflows are covered.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Manages DNS records and Cloudflare Tunnels for a Cloudflare zone via the Cloudflare API. Supports listing, creating, updating, and deleting DNS records, as well as tunnel lifecycle operations.
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables managing REG.RU domain names, DNS zones and records, services, billing, DNSSEC, and account folders through REG.API 2.0 over the Model Context Protocol. Provides tools, resources, and prompts for domain availability checks, DNS record edits, renewals, balance and invoice lookups, plus workflows like expiring-service audits and VPS domain configuration.
      18
      MIT