Domeneshop

Quick start · Client setup · Tools · Access control · Troubleshooting · Get API credentials

An MCP server that turns the Domeneshop API into tools an assistant can call. Every operation the API offers is covered — 17 tools across domains, DNS, HTTP forwarding, dynamic DNS and invoices.

It talks MCP over stdio, so it works with any MCP-compatible client: Claude Code, Claude Desktop, Cursor, VS Code, Codex, Windsurf, Cline and others.

New to MCP? Start here

MCP (Model Context Protocol) is an open standard that lets AI apps call outside tools. This package is an MCP server: a small program your AI app starts in the background and talks to. Once it is registered, you just ask in plain language — "point blog.example.no at 203.0.113.10" — and the assistant picks the right tool, shows you what it is about to do and asks before changing anything.

You never run the server yourself, and you do not need to know the tool names. What you need:

• A Domeneshop API token and secret, a key pair that lets a program act on your account. Treat them like a password.
• An MCP client, the app you chat with. Claude Code is used below; any other works too (see Client setup).
• Node.js 20.3+ (download the LTS) or Homebrew. Not needed for the Claude Desktop bundle.

If you are unsure about letting an assistant change live DNS, start in read-only mode: it can look at everything but change nothing.

Quick start

You need a Domeneshop account, plus either Node.js 20.3 or newer (for npx) or Homebrew.

1. Create an API token and secret at domeneshop.no/admin?view=api.

2. Register the server in Claude Code, replacing the placeholders with your token and secret:

claude mcp add domeneshop \
  --env DOMENESHOP_API_TOKEN=<your-api-token> \
  --env DOMENESHOP_API_SECRET=<your-api-secret> \
  -- npx -y domeneshop-mcp

Add --env DOMENESHOP_READ_ONLY=true to start with read-only tools only, and --scope user to make it available in every project (the default is the current project only).

3. Ask for something. Start a new claude session and try "List my Domeneshop domains". Running /mcp inside Claude Code shows whether the server connected.

Using Homebrew instead of npx? Install once, then register the binary in step 2 with -- domeneshop-mcp in place of -- npx -y domeneshop-mcp:

brew install martinzachariassen/tap/domeneshop-mcp

Using a different client? Claude Desktop has a one-click bundle that needs no Node.js, and Cursor and VS Code have one-click install buttons at the top of this page. Codex and others take a short config block. See Client setup.

What you can ask for

Client setup

The server is launched by your client rather than run by hand. It needs two environment variables, DOMENESHOP_API_TOKEN and DOMENESHOP_API_SECRET; the optional ones are listed under Configuration.

Most clients take the same standard config. Replace the placeholders with your token and secret, and if the file already lists other servers, add the "domeneshop" entry inside the existing "mcpServers" object:

{
  "mcpServers": {
    "domeneshop": {
      "command": "npx",
      "args": ["-y", "domeneshop-mcp"],
      "env": {
        "DOMENESHOP_API_TOKEN": "<your-api-token>",
        "DOMENESHOP_API_SECRET": "<your-api-secret>"
      }
    }
  }
}

Most clients can also scope a server to the current project or make it available everywhere, usually by choosing which config file you write to. The blocks below note this where it applies.

Claude Code

Use the CLI command from Quick start. It defaults to --scope local, private to you and this project. Use --scope project to write <your-project>/.mcp.json instead, shared via version control, or --scope user for every project on your account.

You can also pass the standard config as raw JSON:

claude mcp add-json domeneshop '{"command":"npx","args":["-y","domeneshop-mcp"],"env":{"DOMENESHOP_API_TOKEN":"<your-api-token>","DOMENESHOP_API_SECRET":"<your-api-secret>"}}'

Or write the standard config straight into <your-project>/.mcp.json. claude mcp list shows registered servers and whether they connect.

Claude Desktop

The easiest route is the one-click bundle, which needs no Node.js:

1. Download domeneshop-mcp-<version>.mcpb from the latest release.
2. Open it (double-click, or drag it into Claude Desktop).
3. Paste your token and secret, optionally turn on read-only mode, and install.

Claude Desktop stores the credentials securely.

To configure it by hand instead, add the standard config to claude_desktop_config.json, reachable from Settings → Developer → Edit Config, then restart Claude Desktop:

Cursor

The button installs the server with placeholder credentials. Cursor cannot prompt for them, so afterwards open Settings → MCP, edit the domeneshop entry and replace <your-api-token> and <your-api-secret> with your own.

To set it up by hand instead, add the standard config to an mcp.json file:

VS Code (GitHub Copilot)

The buttons install the server in your user configuration. VS Code then asks for your token and secret and stores them securely, so nothing is written to a config file in plain text.

To set it up by hand instead, note that VS Code uses a servers key instead of mcpServers, and wants an explicit type. For this project only, add it to <your-project>/.vscode/mcp.json:

{
  "servers": {
    "domeneshop": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "domeneshop-mcp"],
      "env": {
        "DOMENESHOP_API_TOKEN": "<your-api-token>",
        "DOMENESHOP_API_SECRET": "<your-api-secret>"
      }
    }
  }
}

For every project, run the command palette action MCP: Open User Configuration and add the same block there, or register it in one line:

code --add-mcp '{"name":"domeneshop","command":"npx","args":["-y","domeneshop-mcp"],"env":{"DOMENESHOP_API_TOKEN":"<your-api-token>","DOMENESHOP_API_SECRET":"<your-api-secret>"}}'

Codex

Codex CLI reads MCP servers from mcp_servers in its config file:

[mcp_servers.domeneshop]
command = "npx"
args = ["-y", "domeneshop-mcp"]
env = { DOMENESHOP_API_TOKEN = "<your-api-token>", DOMENESHOP_API_SECRET = "<your-api-secret>" }

codex mcp add domeneshop -- npx -y domeneshop-mcp registers it from the command line, but takes no env flags, so set the two variables in the [mcp_servers.domeneshop] block it creates.

Any other MCP client

Windsurf, Cline, Continue, LM Studio and anything else that runs MCP servers over stdio will work. Most use the same shape as the standard config above; check your client's documentation for the config file and key name, then point it at:

• command: npx
• args: ["-y", "domeneshop-mcp"]
• env: DOMENESHOP_API_TOKEN and DOMENESHOP_API_SECRET

Skipping npx (npm or Homebrew)

To avoid resolving the package on every launch, install it once and use domeneshop-mcp as the command with no args. With npm:

npm install -g domeneshop-mcp

Or with Homebrew on macOS or Linux, which also installs Node.js for you if it is missing:

brew install martinzachariassen/tap/domeneshop-mcp

brew upgrade domeneshop-mcp picks up new releases. GUI apps such as Claude Desktop usually do not see Homebrew's PATH, so give them the full path (brew --prefix prints the prefix: /opt/homebrew on Apple silicon, /usr/local on Intel Macs, /home/linuxbrew/.linuxbrew on Linux):

{
  "mcpServers": {
    "domeneshop": {
      "command": "/opt/homebrew/bin/domeneshop-mcp",
      "env": {
        "DOMENESHOP_API_TOKEN": "<your-api-token>",
        "DOMENESHOP_API_SECRET": "<your-api-secret>"
      }
    }
  }
}

Configuration

All settings are environment variables, passed with --env in Claude Code or in the env block of the config above. Only the first two are required.

Tools

Every tool declares MCP annotations and a title, so clients know which ones are safe to run without asking you first. The Access column below mirrors those annotations. Arguments are validated before anything is sent to Domeneshop (TTL range, URL scheme, IP addresses, and the fields each record type requires), and read-only tools also return structured output for clients that support it.

Domains

DNS

Heads up: update_dns_record replaces the whole record rather than patching it. Any field left out is dropped, and omitting ttl resets it to the default 3600 seconds. Use patch_dns_record to change only some fields. upsert_dns_record refuses to act when a host has several records of the same type (typical for MX and TXT) and lists their IDs instead.

HTTP forwarding

Dynamic DNS

Invoices

Access control

The Domeneshop API has no scoped tokens: a token can do everything the account can. To limit what the assistant can do, limit which tools the server exposes. Hidden tools are not registered at all, so the model never sees them.

• Read-only mode. Set DOMENESHOP_READ_ONLY=true to expose only the eight read-only tools. This is a good default if you mainly ask questions about your domains, DNS and invoices, or are trying the server out for the first time.
• Allowlist. Set DOMENESHOP_TOOLS=list_domains,list_dns_records,patch_dns_record to expose exactly those tools.
• Denylist. Set DOMENESHOP_DISABLED_TOOLS=delete_dns_record,delete_forward to hide specific tools.

The settings combine, and a misspelled tool name stops the server at startup instead of being silently ignored.

Most clients ask before running a tool not annotated read-only. Keep that confirmation on for this server: write tools change live DNS, and a wrong record can take a site or mailbox offline.

Credentials are only ever sent to api.domeneshop.no and are never logged. To revoke access, delete the token in the Domeneshop control panel.

Troubleshooting

• The tools do not show up: restart the client (most only load servers at startup) or, in Claude Code, check /mcp. Run npx -y domeneshop-mcp --version to check that Node.js 20.3+ and npx work. If you edited a JSON config by hand, make sure it is still valid JSON. With DOMENESHOP_DEBUG=true the server logs every API request (method, path, status and duration, never credentials) to stderr, which most clients capture in their MCP logs.
• API returned status 401: the token or secret is wrong. Copy both again from domeneshop.no/admin?view=api. Surrounding whitespace is trimmed automatically.
• API returned status 404: the domain or record ID does not exist on this account. Ask the assistant to list domains or records first.
• Timeouts: requests give up after 30 seconds. Idempotent requests are retried on rate limiting and temporary errors. Raise the limit with DOMENESHOP_TIMEOUT_MS if needed.
• A DNS change does not show up: DNS is cached for the record's TTL (3600 seconds by default), so other resolvers may serve the old value for up to an hour. Ask the assistant to show the record to confirm Domeneshop stored it.

Still stuck? Open an issue.

Reference

Supported DNS record types

All eleven record types Domeneshop accepts are supported, with their type-specific fields:

The tag field is deliberately untyped: it is a numeric key tag for DS and a property tag such as issue for CAA, and Domeneshop documents neither.

Undocumented Domeneshop API behaviour

A few things this server relies on are not in Domeneshop's published OpenAPI spec, but are supported and used by their own client libraries:

• The spec documents seven record types; ANAME, CAA, DS and NS work too, as the record validation in domeneshop.js and python-domeneshop shows.
• GET /invoices accepts a status filter, which domeneshop.js uses.
• POST /forwards/ answers 201 with an empty body and names the new forward only in the Location header.
• GET /dyndns/update answers 204 with no body rather than JSON, so the client does not try to decode it.

Distribution

• npm package
• Homebrew tap
• MCP Registry
• Claude Desktop bundle (.mcpb on each release)

Development

npm install          # install dependencies
npm run dev          # run the server from source with tsx
npm run build        # compile to ./dist
npm run typecheck    # type-check without emitting
npm run lint         # lint with Biome
npm run format       # format with Biome
npm test             # run the test suite (vitest)

The tests stub the Domeneshop API with a local node:http server and drive the MCP server over an in-memory transport, so they need no credentials and make no network calls.

Project layout

src/
  domeneshop/       Domeneshop API client (HTTP transport + one resource per endpoint group)
  mcp/              MCP server: tool registration, schemas, result/error helpers
  index.ts          CLI entry point
test/
  domeneshop/       Client tests, against a local HTTP server
  mcp/              End-to-end tool tests, against an in-memory MCP transport

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md for the development workflow and changelog conventions. Everyone taking part is expected to follow the Code of Conduct.

Security

See SECURITY.md for how to report a vulnerability.

License

MIT