Domeneshop MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Domeneshop MCP preview adding A record for example.com to 203.0.113.5"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
/mcpfor 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 |
| Required upstream API token |
| Required upstream API secret |
|
|
| Optional comma-separated exact domain names; omitted = all |
| Backups/receipts, default |
| Required for HTTP; separate random secret, at least 32 characters |
| HTTP Host allowlist; local hosts by default; explicit for non-loopback binds |
| 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-mcpPoint 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 8000The 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
list_domains,list_dns_recordsandlist_forwardsinspect current state.Call
setup_website,add_verification_txt,plan_dns_batchor a CRUD tool to get a preview.Inspect
actions,before,after, warnings and expiry. The caller must have user authorization.Call
apply_plan(plan_id)to execute. Check its returned status.get_planretrieves the result;export_zonereads 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 |
| All planned operations passed independent API readback and state checks |
| Upstream accepted DDNS but intended address was not proven |
| 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 toolsaccount_overviewBRead-onlyIdempotent
Summarize domain counts, statuses and domains expiring within the chosen period.
Inputs: expiry_days. Returns: object
add_verification_txtBRead-only
Preview adding a TXT verification token without replacing existing TXT/SPF records.
Inputs: value (required), domain (required), ttl, host. Returns: object
apply_planADestructive
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_dnsARead-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_recordsARead-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_recordARead-only
Preview adding one record. Identical records are a no-op; use apply_plan to write.
Inputs: domain (required), record (required). Returns: object
create_forwardBRead-only
Preview a new HTTP forward with DNS collision checks.
Inputs: domain (required), forward (required). Returns: object
delete_dns_recordBRead-only
Preview deletion of an exact DNS record; shows its current contents.
Inputs: domain (required), record_id (required). Returns: object
delete_forwardCRead-only
Preview deletion of a specific HTTP forward.
Inputs: host (required), domain (required). Returns: object
ensure_dns_recordsCRead-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_zoneBRead-onlyIdempotent
Export a complete JSON snapshot of DNS and forwards; no filesystem write.
Inputs: domain (required). Returns: object
get_dns_recordCRead-onlyIdempotent
Read the exact DNS record ID within a domain.
Inputs: domain (required), record_id (required). Returns: object
get_domainBRead-onlyIdempotent
Get domain registration, expiry, nameservers and enabled services.
Inputs: domain (required). Returns: object
get_forwardCRead-onlyIdempotent
Get the forward for a relative host, e.g. www or @.
Inputs: host (required), domain (required). Returns: object
get_invoiceBRead-onlyIdempotent
Get a single account invoice by invoice number.
Inputs: invoice_id (required). Returns: object
get_planBRead-onlyIdempotent
Read a plan preview or the stored execution result in this process.
Inputs: plan_id (required). Returns: object
list_dns_recordsBRead-onlyIdempotent
List DNS, optionally filtering relative host (e.g. @, www) and record type.
Inputs: domain (required), host, record_type. Returns: object
list_domainsARead-onlyIdempotent
List account domains; optional substring search. Returns deterministic count.
Inputs: query. Returns: object
list_forwardsCRead-onlyIdempotent
List HTTP/WWW forwards for a domain.
Inputs: domain (required). Returns: object
list_invoicesARead-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_batchARead-only
Preview up to 100 ordered creates/updates/deletes. Batch execution is non-atomic.
Inputs: domain (required), changes (required). Returns: object
replace_ipBRead-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_backupARead-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_websiteBRead-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_recordBRead-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_dnsARead-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_forwardBRead-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
Scored across 27 tools
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.
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.
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.
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
List domains and expiry dates; read, create and update LiveDNS records in Gandi.
Manage Kubana Cloud DNS zones and A, AAAA, CNAME, MX, TXT and NS records; check delegation.
MCP server for DNSimple — domains, DNS zone records, availability, pricing and contacts.
Check domain availability, list domains and DNS zones, change DNS records in INWX.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceManages 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
- FlicenseNot gradedqualityBmaintenanceEnables authenticated management of GoDaddy domains and DNS records through JSON-RPC tools, with domain allowlisting, dry-run planning, and support for Microsoft 365 and SSL DNS configurations.-
- AlicenseBqualityBmaintenanceEnables 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.18MIT
- AlicenseBqualityCmaintenanceProvides typed tools for DNS, zone, and cache management plus a universal passthrough to any Cloudflare API v4 endpoint, with confirmation required for destructive operations.8MIT