{ "markdown": "# hetzner-dns-mcp\n\n\n\n[![CI](https://img.shields.io/github/actions/workflow/status/ni-c/hetzner-dns-mcp/ci.yml?branch=main&label=CI)](https://github.com/ni-c/hetzner-dns-mcp/actions/workflows/ci.yml)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ni-c/hetzner-dns-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/ni-c/hetzner-dns-mcp)\n\"Socket\n[![Glama score](https://glama.ai/mcp/servers/ni-c/hetzner-dns-mcp/badges/score.svg)](https://glama.ai/mcp/servers/ni-c/hetzner-dns-mcp)\n
\n[![npm version](https://img.shields.io/npm/v/hetzner-dns-mcp)](https://www.npmjs.com/package/hetzner-dns-mcp)\n[![container image](https://img.shields.io/badge/ghcr.io-ni--c%2Fhetzner--dns--mcp-4f46e5?logo=docker&logoColor=white)](https://github.com/ni-c/hetzner-dns-mcp/pkgs/container/hetzner-dns-mcp)\n[![HTTP via mcp-hub](https://img.shields.io/badge/HTTP-via%20mcp--hub-4f46e5?logo=modelcontextprotocol&logoColor=white)](https://mcp-hub.ni-c.de)\n
\n[![docs](https://img.shields.io/badge/docs-hetzner--dns--mcp.ni--c.de-4f46e5?logo=readthedocs&logoColor=white)](https://hetzner-dns-mcp.ni-c.de)\n[![sponsor](https://img.shields.io/badge/sponsor-ni--c-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/ni-c)\n\n\nA [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for managing DNS zones and records via the [Hetzner Cloud API](https://docs.hetzner.cloud/reference/cloud#zones).\n\nLets MCP clients like Claude Code, Claude Desktop or Codex manage your Hetzner DNS: list, create, update and delete zones and RRSets (record sets), import/export zone files, manage protection and TTLs, and track asynchronous zone actions.\n\nTwenty-two tools is the ceiling, not the floor: `HETZNER_ALLOW_TOOLS=essential`\nregisters a curated eight instead, and a model picks the right tool far more\nreliably from eight than from twenty-two — see\n[choosing which tools load](#choosing-which-tools-load).\n\n> **Note:** This server targets the current DNS API that is part of the **Hetzner Cloud API** (`api.hetzner.cloud`). The legacy DNS API (`dns.hetzner.com`) was shut down in May 2026 and is not supported.\n\n![Demo: listing the tools, a refused set_records call, and the same call succeeding with the confirmation token it returned](https://hetzner-dns-mcp.ni-c.de/demo.gif)\n\n\n

\n \n \n \n \"An\n \n

\n\n\n\n \n \n \"An\n\n\n## What makes it different\n\n**Zones, record sets and the actions behind them.** Listing, creating, updating\nand deleting zones and RRSets, importing and exporting BIND zone files, changing\nTTLs and protection — and following the asynchronous zone actions Hetzner queues\nbehind a change, rather than reporting success and leaving you to guess.\n\n**Nothing upstream is trusted.** Record values, comments and zone files come back\nwrapped as untrusted data, secret-looking keys are redacted, oversized values are\ntruncated and HTML error pages are dropped instead of pasted into the context.\n\n**Destructive calls ask a person.** Deleting a zone or replacing a record set\nraises a real dialog through MCP elicitation. Where the client cannot show one,\nthe call is refused and carries a random single-use token that only ever appeared\nin a previous tool result — so nothing hidden inside a DNS record can mint it.\n\n## Requirements\n\n- Node.js ≥ 22\n- A Hetzner Cloud API token for the project that holds your DNS zones — create one in the [Hetzner Cloud Console](https://console.hetzner.com) under _your project → Security → API tokens_. Use a **read & write** token for full functionality (a read-only token limits you to the read tools).\n\n## Configuration\n\nConfiguration is provided via environment variables:\n\n| Variable | Required | Description |\n| ---------------------- | -------- | ---------------------------------------------------------------------------------- |\n| `HETZNER_API_TOKEN` | yes | Hetzner Cloud API token (project-scoped) |\n| `HETZNER_READ_ONLY` | no | `true` registers only the read tools; the write tools do not exist at all |\n| `HETZNER_ALLOW_TOOLS` | no | Comma-separated tool names, `list_*` prefixes, or `essential` for a curated preset |\n| `HETZNER_DENY_TOOLS` | no | Same syntax; removed from whatever `HETZNER_ALLOW_TOOLS` left |\n| `ELICITATION` | no | `false` replaces the approval dialog with the two-call token. **Not prefixed** |\n| `HETZNER_API_BASE_URL` | no | Base URL of the API (default: `https://api.hetzner.cloud/v1`) |\n\nWithout a token the server still starts and lists its tools (so registries and\ninspectors can introspect it), but every tool call fails with setup\ninstructions instead of reaching the API.\n\n`HETZNER_API_TOKEN` and `HETZNER_API_BASE_URL` are deleted from the process\nenvironment once they have been read, so a later crash report or diagnostic\ndump cannot expose the token.\n\n### Choosing which tools load\n\n`HETZNER_ALLOW_TOOLS` and `HETZNER_DENY_TOOLS` take comma-separated tool names;\na trailing `*` matches a whole family. `essential` is a curated preset —\n`list_zones`, `get_zone`, `list_rrsets`, `get_rrset`, `create_rrset`,\n`set_records`, `delete_rrset` and `export_zonefile` — which covers reading a\nzone and changing a record without the rare, catastrophic tools.\n\n```sh\nHETZNER_ALLOW_TOOLS=essential\nHETZNER_ALLOW_TOOLS=list_*,get_zone,set_records\nHETZNER_DENY_TOOLS=delete_zone,import_zonefile\n```\n\nAn entry that matches no tool aborts startup and names it, so a typo cannot\nsilently hide a tool — an absent tool is not something anyone traces back to an\nenvironment variable. A filtered tool is never registered, so it is absent from\n`tools/list` and unknown to `tools/call` alike, exactly like a write tool under\n`HETZNER_READ_ONLY`.\n\nIf you run several of these servers at once, [mcp-hub](https://mcp-hub.ni-c.de)\nis the other answer — its `/hub` endpoint replaces every server's tools with six\nmeta-tools.\n\n## Installation\n\n### Claude Code\n\n```bash\nclaude mcp add hetzner-dns -s user \\\n -e HETZNER_API_TOKEN=your-token \\\n -- npx -y hetzner-dns-mcp\n```\n\n### Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"hetzner-dns\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"hetzner-dns-mcp\"],\n \"env\": {\n \"HETZNER_API_TOKEN\": \"your-token\"\n }\n }\n }\n}\n```\n\n### Codex\n\nAdd to your `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.hetzner-dns]\ncommand = \"npx\"\nargs = [\"-y\", \"hetzner-dns-mcp\"]\nenv = { HETZNER_API_TOKEN = \"your-token\" }\n```\n\n### From source\n\n```bash\ngit clone https://github.com/ni-c/hetzner-dns-mcp.git\ncd hetzner-dns-mcp\nnpm install\nnpm run build\n# then use `node /path/to/hetzner-dns-mcp/dist/index.js` as the command\n```\n\n### Docker\n\nMulti-arch images (amd64/arm64) are published to GHCR with an SBOM and build\nprovenance:\n\n```bash\ndocker run -i --rm -e HETZNER_API_TOKEN=your-token ghcr.io/ni-c/hetzner-dns-mcp\n```\n\nThe image talks MCP over stdio, so clients need `docker run -i` (no port is\nexposed):\n\n```json\n{\n \"mcpServers\": {\n \"hetzner-dns\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"-i\",\n \"--rm\",\n \"-e\",\n \"HETZNER_API_TOKEN\",\n \"ghcr.io/ni-c/hetzner-dns-mcp\"\n ],\n \"env\": {\n \"HETZNER_API_TOKEN\": \"your-token\"\n }\n }\n }\n}\n```\n\n### Through mcp-hub\n\nA client that cannot spawn a local process — ChatGPT connectors, Claude on the web,\nCursor, LibreChat — reaches hetzner-dns-mcp through [mcp-hub](https://mcp-hub.ni-c.de): one\ncontainer serves many stdio MCP servers over Streamable HTTP, with an OAuth 2.1 login\nbehind a single password and long-lived tokens for the clients that cannot do OAuth. Its\n`/hub` endpoint puts every server behind six meta-tools, so one connector reaches all of\nthem without N×tool schemas in the model's context, and it speaks both protocol revisions\n— a question this server asks travels through it to the person at the far end.\n\nIts `/config/mcp.json` uses Claude Code's format, so the entry is the one you already\nhave:\n\n```json\n{\n \"mcpServers\": {\n \"hetzner-dns\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"hetzner-dns-mcp\"],\n \"env\": {\n \"HETZNER_API_TOKEN\": \"your-token\",\n \"HETZNER_ALLOW_TOOLS\": \"essential\"\n },\n \"denyTools\": [\"delete_*\"]\n }\n }\n}\n```\n\n`allowTools` and `denyTools` there are the hub's **own** per-server filter, which is not\nthe same thing as `*_ALLOW_TOOLS` in `env` — the difference, and the mistake it invites,\nare in the [client guide](https://hetzner-dns-mcp.ni-c.de/guide/clients#through-mcp-hub).\n\n## Tools\n\nEvery tool declares an `outputSchema` and answers with `structuredContent`\nalongside the text block, so a client can use the result without parsing prose.\nThe `` fence stays in the text — it is the readable presentation\nof the same marker — and the structured half carries `untrusted: true` and\n`source: \"hetzner-cloud-api\"` as fields. **Every** tool carries them: record\nvalues, comments, labels and zone files are written by whoever controls the\nzone, and no tool here answers with anything else.\n\nThe API documents are described as open objects with the top-level keys the\n[spec](https://docs.hetzner.cloud/cloud.spec.json) guarantees. The API is not\nthis server's to promise, and the SDK validates each result against its schema\nbefore it goes out — a strict shape would turn a field Hetzner adds into a tool\nthat fails outright.\n\nAn over-budget result is now an **error**. It used to be cut off mid-document\nand say so, which is fine for a text block and impossible for\n`structuredContent`: the two channels have to carry the same value, and a\ndocument sliced mid-string does not parse.\n\n### Zones\n\n| Tool | Description |\n| ------------------------------- | --------------------------------------------------------------- |\n| `list_zones` | List zones with status, mode, nameservers and record counts |\n| `get_zone` | Get the full details of a single zone |\n| `create_zone` | Create a primary or secondary zone, optionally from a zone file |\n| `update_zone` | Replace the labels of a zone |\n| `delete_zone` 👤 | Permanently delete a zone |\n| `export_zonefile` | Export the zone as a BIND zone file |\n| `import_zonefile` 👤 | Import a BIND zone file (replaces all records) |\n| `change_zone_ttl` | Change the default TTL of a zone |\n| `change_zone_protection` 👤 | Enable/disable delete protection — asks when _disabling_ |\n| `change_primary_nameservers` 👤 | Replace the primaries of a secondary zone |\n\n### RRSets (record sets)\n\n| Tool | Description |\n| ---------------------------- | ---------------------------------------------------------------------------- |\n| `list_rrsets` | List the RRSets of a zone, filterable by name/type/labels |\n| `get_rrset` | Get a single RRSet by name and type |\n| `create_rrset` 👤 | Create a new RRSet with records — asks for authority records |\n| `update_rrset` | Replace the labels of an RRSet |\n| `delete_rrset` 👤 | Permanently delete an RRSet |\n| `set_records` 👤 | Replace **all** records of an RRSet |\n| `add_records` 👤 | Add records to an RRSet (creates it if missing) — asks for authority records |\n| `remove_records` 👤 | Remove specific records from an RRSet |\n| `change_rrset_ttl` | Change the TTL of an RRSet (or reset to the zone default with `null`) |\n| `change_rrset_protection` 👤 | Enable/disable change protection — asks when _disabling_ |\n\n👤 asks a person through MCP elicitation · falls back to a two-call\n`confirm_token` where the client cannot show a dialog.\n\n### Actions\n\n| Tool | Description |\n| ------------------- | ------------------------------------------------------------------ |\n| `list_zone_actions` | List asynchronous zone operations (e.g. imports), filter by status |\n| `get_zone_action` | Get a single action by ID to check its status |\n\n### Safety\n\n**A person is asked, not just told.** Every irreversible tool — `delete_zone`,\n`delete_rrset`, `import_zonefile`, `set_records`, `remove_records`,\n`change_primary_nameservers`, and\n`change_zone_protection`/`change_rrset_protection` when they _remove_ protection —\nraises a real dialog through MCP elicitation where the client supports it. The model\ncannot answer it on its behalf, and nothing happens until an answer comes back.\n\nThree more ask _conditionally_, because in DNS the dangerous act is making a claim\nrather than withdrawing one: `create_rrset` and `add_records` for a name or type\nthat decides who answers (`NS`, `DS`, `MX`, `CNAME`, `CAA`, `TLSA`, `SVCB`,\n`HTTPS`, `SRV`, the apex `@`, a wildcard), and `create_zone` when the call carries\n`primary_nameservers` or a `zonefile` — the same payloads\n`change_primary_nameservers` and `import_zonefile` are guarded for. The\nconfirmation binds every field the call will write, TTL and labels included, so a\ntoken issued for one TTL cannot redeem another.\n\nWhere the client cannot show a dialog, the tool refuses its first call and returns a\nrandom, single-use token valid for five minutes; the second call must repeat the\nidentical arguments and pass it:\n\n```text\n1. set_records(zone: \"example.com\", name: \"www\", type: \"A\", records: [{value: \"198.51.100.1\"}])\n → error: Refusing to replace the records … confirm_token: \"3f9c…\"\n2. set_records(…same arguments…, confirm_token: \"3f9c…\")\n → executed\n```\n\nDeliberately not a boolean the model can set on its own: the token exists only in a\n_previous_ tool result, so an instruction hidden in a TXT record or a zone-file\ncomment cannot manufacture one. But it proves the call was made twice with the same\narguments and nothing more, and the fallback text says so rather than implying\nsomebody approved.\n\nEither way the approval is bound to what it is about. For `set_records`,\n`remove_records` and `import_zonefile` that is a hash of the exact payload: an\napproval for `[\"198.51.100.1\"]` will not write `[\"198.51.100.66\"]`.\n\n`ELICITATION=false` takes the fallback path deliberately, for a scheduled job or a\ntest harness. It never removes the guard. See\n[Asking a person](https://hetzner-dns-mcp.ni-c.de/guide/approval).\n\nThe dialog is a guard rail, not a security boundary — the boundary is the permission\nprompt of your MCP host. Do not auto-approve these tools.\n\n**Untrusted upstream data.** Everything the API returns is wrapped in an\n`` envelope, because record values, comments, labels and zone files are\nwritten by whoever controls the zone. Confirmation messages never quote that content;\nthey report counts and TTLs only. Keys that look like secrets (`tsig_key`, `token`,\n`secret`, `password`) are redacted from results, oversized values are truncated, and\nHTML error pages from an intermediate proxy are dropped rather than pasted into the\nmodel's context.\n\n**Least privilege.** Set `HETZNER_READ_ONLY=true` to register only the seven read\ntools — the write tools then do not exist on the protocol at all, rather than failing\nat call time. Combine it with a read-only Hetzner token for a genuinely read-only\nsetup.\n\n**Other guarantees.**\n\n- Tools carry MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`) so hosts can apply appropriate permission policies.\n- `HETZNER_API_BASE_URL` must be an `https` URL (`http` is only accepted for localhost) and must not contain credentials; a warning is printed when a non-default host is configured, because the API token is sent there.\n- Zone identifiers and RRSet names are validated against a strict character set — no slashes, no percent signs, no bare `.` or `..` — so a request cannot escape the intended API path; requests never follow redirects, so the Bearer header cannot be replayed elsewhere.\n- TSIG keys passed to `create_zone`/`change_primary_nameservers` become part of the conversation context and client transcripts — treat them as secrets and rotate them if in doubt.\n- Hetzner-side resource protection is honored: protected zones/RRSets return an error with a hint to the corresponding `change_*_protection` tool.\n\n## Not exposed, on purpose\n\n**Only the Hetzner Cloud DNS API.** The standalone `dns.hetzner.com` API was shut\ndown in May 2026 and is not implemented — scripts still using it are broken for\nreasons that have nothing to do with this server.\n\n**`HETZNER_API_BASE_URL` is not a provider switch.** It exists to point at a local\nmock during development, and is validated (HTTPS only, no credentials in the URL,\na warning on a non-default host) precisely because your token is sent there. The\nrequest shapes are Hetzner's.\n\n## Safety\n\n- DNS records are edited by whoever holds the token, so upstream values,\n comments and zone files are marked as untrusted data — to be reported, never\n followed, in both channels and behind a fence the data cannot close. Keys are\n redacted by the suffix of their normalised name (`password`, `secret`,\n `token`, `apikey`, `privatekey`, `passphrase`, `tsigkey`), values over 4 000\n characters are truncated, control characters are stripped, and an HTML error\n page is dropped rather than pasted into the context.\n- Deleting a zone or replacing a record set asks a person: a real dialog through\n MCP elicitation, bound to the exact target. Where the client cannot show one,\n the call is refused and carries a random single-use token that only ever\n appeared in a previous tool result.\n- `HETZNER_READ_ONLY=true` registers the seven read tools and nothing else — a\n write tool is then absent from `tools/list`, not refused when called.\n- Requests are hardened rather than trusted: zone identifiers are pattern-matched\n so a path cannot escape, redirects are refused so the `Authorization` header\n never follows one, every request times out after 30 seconds, request bodies are\n assembled from named fields only, and the base URL is validated (HTTPS, no\n credentials) before the token is ever sent to it. The token's own shape is\n checked before it reaches the HTTP layer, which would otherwise quote it back\n in an error; response bodies are read under a ceiling with the status decided\n first; and every response is shape-checked rather than cast, so a proxy's\n answer produces a readable result rather than a schema violation with no\n cause.\n\n## Documentation\n\nThe full guide, tool reference and security notes live at\n**[hetzner-dns-mcp.ni-c.de](https://hetzner-dns-mcp.ni-c.de)** (source in [`docs/`](docs/)).\n\n## Development\n\n```bash\nnpm install\nnpm run build # compile TypeScript to dist/\nnpm test # run the vitest test suite\nnpm run lint # oxlint + prettier check\n```\n\n### Releasing\n\n1. Bump the version in `package.json` (`npm version X.Y.Z --no-git-tag-version`).\n2. Rename the `[Unreleased]` section in `CHANGELOG.md` to the new version.\n3. Commit, then tag and push: `git tag -a vX.Y.Z -m \"vX.Y.Z\" && git push origin main vX.Y.Z`.\n\nThe release workflow then runs the tests, publishes to npm via\n[Trusted Publishing](https://docs.npmjs.com/trusted-publishers) (with\nprovenance), creates a GitHub release with the notes from the CHANGELOG and\nupdates the entry in the official\n[MCP Registry](https://registry.modelcontextprotocol.io)\n(`io.github.ni-c/hetzner-dns-mcp`, via GitHub OIDC).\n\n## Releasing\n\nReleases are tag-driven. Bump `package.json`, move the `[Unreleased]` notes in\n`CHANGELOG.md` under the new version, commit, then:\n\n```sh\ngit tag -s vX.Y.Z -m \"vX.Y.Z\"\ngit push origin main vX.Y.Z\n```\n\nThe release workflow publishes to npm via Trusted Publishing (OIDC, with\nprovenance), pushes the multi-arch container image to GHCR, creates the GitHub\nrelease from the CHANGELOG section, and updates the entry in the official MCP\nregistry.\n\n## Contributing\n\nIssues, discussions and pull requests are welcome — see\n[CONTRIBUTING.md](CONTRIBUTING.md). For vulnerabilities please use\n[private reporting](https://github.com/ni-c/hetzner-dns-mcp/security/advisories/new)\nrather than a public issue; the policy is in [SECURITY.md](SECURITY.md).\n\n## License\n\n[MIT](LICENSE) © Willi Thiel\n", "bytes": 22932, "sha": "bbea641843411a4550a91730a8ea77383ba01c8bdadfa960fcecd37dbc13fca6", "repo_slug": "ni-c/hetzner-dns-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_ni_c_hetzner_dns_mcp_a6312341/readme" }