namecheap-mcp

An MCP server that gives an AI agent safe, high-level control over your domains and DNS across three providers: Namecheap, GoDaddy (v3) and AWS Route 53.

One tool surface. A domain routes to whichever provider actually holds it; you can override with provider on any tool. The name is historical — it started as Namecheap-only.

It is built for Claude Code, Claude Desktop, and any other MCP client that speaks stdio.

The three providers do not agree

This is the part worth reading before you use it. The tools hide the wire formats, not the semantics.

Two of those bite:

• GoDaddy edits are not atomic. v3 has no record-update endpoint. An edit is a DELETE then a POST. If the POST fails, the record is absent, not stale. Every write that does this returns nonAtomicWarning saying so — read it before assuming the zone is what you asked for.

• Route 53's unit is a record set. Three A records at www are three rows here and one set there. Deleting one of three by emitting a DELETE would take all three; this server emits an UPSERT carrying the survivors. The zone's own SOA and apex NS are never touched, because Route 53 creates both with the hosted zone and rejects deleting either.

A capability a provider lacks is an answer, not an error: the tool returns a sentence naming the provider, why its API has no such thing, and where you can do it instead. Nothing is changed.

Related MCP server: domain-suite-mcp

Why this isn't a 1:1 mirror of any provider's API

Each provider's API is a flat catalogue with its own sharp edges. Handing those to an agent verbatim is a footgun. This server exposes a smaller set of task-shaped tools designed for an LLM to call correctly:

• domains.dns.setHosts is REPLACE-ALL. It overwrites every host record on a domain with exactly the set you submit — omit your MX records and your mail silently breaks. A naive "add a TXT record" tool that forwarded straight to setHosts would wipe the zone. So modify_dns_records here is a read-modify-write engine: it reads the current zone, applies granular add/update/delete operations in memory, and submits the full resulting set. Agents express intent, never hand-assemble the whole zone. A separate, explicitly-named replace_all_dns_records exists for the rare deliberate full rewrite, and it refuses to blank a non-empty zone unless you pass allowEmptyZone: true.

• Money-spending actions are gated. register_domain, renew_domain, reactivate_domain and transfer_domain are annotated destructive and require confirm: true. Called without it, they return a dry-run preview of what would be charged instead of spending.

• Structured output + tool annotations. Every tool returns both a human summary and a typed structuredContent payload, and carries readOnlyHint / destructiveHint / idempotentHint annotations so the client can reason about safety.

• Errors become guidance. Namecheap's cryptic error numbers are mapped to actionable hints — the single most common failure ("Invalid request IP") is turned into a step-by-step whitelist fix.

• Provenance on every answer. Each result carries provider, account and environment. A caller that cannot tell which provider answered cannot check the answer.

• Types and TTLs are checked against the provider that will receive them. The schema accepts the union of all three, so you are never told "invalid enum" for a type that is valid where your domain lives; the refusal names the provider and lists what it does have. A TTL outside the provider's range is clamped and the clamp is reported — asking for 60 on GoDaddy gets you 600, and you are told.

Prior art: johnsorrentino/mcp-namecheap, which covers 3 read/nameserver tools. This project is an independent, from-scratch implementation with a broader, safety-first tool surface; credit to that project for charting the territory.

Tools

"paid" tools spend real money in production and require confirm: true; without it they return a preview.

Every tool that names a domain also takes an optional provider (namecheap | godaddy | route53) to override routing. You need it for a domain that does not exist yet, since routing works by asking who holds it.

Six tools are Namecheap-only in practice — renew_domain, reactivate_domain, set_domain_lock, set_domain_privacy, get_email_forwarding / set_email_forwarding, and get_domain_info. Called against a domain at another provider they refuse and say why. A domain that resolves nowhere still proceeds: that is the registration and transfer-in case.

Install & configure

Requires Node.js 20+.

Claude Code

claude mcp add namecheap \
  --env NAMECHEAP_API_USER=your_user \
  --env NAMECHEAP_API_KEY=your_key \
  --env NAMECHEAP_CLIENT_IP=your_whitelisted_ip \
  --env NAMECHEAP_SANDBOX=true \
  -- npx -y namecheap-mcp

Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "namecheap": {
      "command": "npx",
      "args": ["-y", "namecheap-mcp"],
      "env": {
        "NAMECHEAP_API_USER": "your_user",
        "NAMECHEAP_API_KEY": "your_key",
        "NAMECHEAP_CLIENT_IP": "your_whitelisted_ip",
        "NAMECHEAP_SANDBOX": "true"
      }
    }
  }
}

Start in sandbox (NAMECHEAP_SANDBOX=true) and switch to production only once you've verified the behaviour — production register/renew/transfer calls spend real money.

From source

git clone https://github.com/fledgeling-co/namecheap-mcp.git
cd namecheap-mcp
npm install        # runs the build via the prepare hook
npm test
node dist/index.js # expects the NAMECHEAP_* env vars to be set

Configuration (environment variables)

GoDaddy is off unless one of its variables is set; the startup banner says godaddy=off. Route 53 is off if the aws binary is absent, and the banner says so rather than letting it look like a routing miss.

A malformed GODADDY_ACCOUNTS is reported by label, never by contents — the contents are a token, and the underlying JSON.parse error can quote the input verbatim.

The API key is only ever sent in the request body and is never written to logs or stdout (which is the MCP protocol channel — all diagnostics go to stderr).

Route 53

Reached by spawning the aws CLI, not the SDK: the CLI already resolves profiles, SSO sessions and assumed roles, and reimplementing that to save a subprocess is a bad trade. Arguments go through execFile, never a shell, and the change batch goes in on stdin — a record value is caller-supplied, and neither a shell string nor a temp file is safe for one.

Reads follow pagination. A zone read short and written back deletes everything past the first page.

scripts/verify-route53.mts reads every hosted zone, diffs each against itself asserting zero changes, and drops one value from a multi-value set asserting the result is one UPSERT carrying the rest. Verified across 8 zones, 190 rows, 95 sets.

GoDaddy

v3 only, Authorization: Bearer {PAT}. The sso-key {KEY}:{SECRET} scheme in GoDaddy's own DNS announcement belongs to v1.

v3 has no list-domains endpoint, so routing probes GET /domain-names/{domain} per configured account and caches the answer, including the miss. A 404 or 403 means "not this account" and the probe moves on — GoDaddy's quickstart says a 403 can mean the account is not eligible for the API at all, and does not say what eligibility is.

Registration is not implemented. v3 has POST /registrations, but using it means modelling contacts, consent records and agreement acceptance, and every test run spends real money. The capability is not claimed rather than half-built.

scripts/verify-godaddy.mts <domain> [--write] exercises a real account. Read-only without --write.

Namecheap API prerequisites

Before anything works you must, at Namecheap → Profile → Tools → API Access:

1. Enable API access on your account.

2. Whitelist the IP the requests originate from (the machine running this server).

Namecheap also gates production API access behind eligibility — per their API FAQ your account must have at least one of:

• 20+ domains in your account, or

• $50+ in account balance, or

• $50+ spent in the last 2 years.

The sandbox (https://www.sandbox.namecheap.com, separate credentials) has none of these requirements — always develop against it first.

Rate limits

Namecheap's documented ceilings are 50 requests/minute, 700/hour, 8000/day per key. This server runs a small client-side limiter (~45/min) that delays rather than fails bursty tool calls to keep you under the per-minute wall. Note that get_domain_pricing issues one API call per TLD.

Error handling

Namecheap returns numeric error codes; this server maps the common ones to actionable guidance, including:

• 1011150 — Invalid request IP → the exact whitelist steps (this is the #1 first-run failure).

• 1011102 / "API key is invalid" → check the key and that the IP is whitelisted / API access is enabled.

• Order/charge failures (2528166, insufficient funds) → check get_account_balance.

• 2020166 — renewal not permitted → the domain is likely expired; use reactivate_domain.

• Extended-attribute, phone-format and DNS-provider errors → what to fix.

Unknown codes are surfaced verbatim so nothing is hidden.

Development

npm run build          # tsc -> dist/
npm test               # vitest
npm run typecheck      # tsc -p tsconfig.test.json  (covers src, test and scripts)
npm run typecheck:build # tsc --noEmit  (src only, matching the build)

153 tests, none needing the network. The pure logic — XML envelope parsing, the DNS read-modify-write engine, the rrset expand/regroup/diff, error-code mapping, transfer-status mapping, config handling — runs against fixtures. Providers are driven through injected fetch and an injected aws runner. The tool layer is driven through the registered handlers against fake providers.

Two scripts need real credentials and sit outside the gate:

npx tsx scripts/verify-route53.mts                      # every zone, read-only
npx tsx scripts/verify-route53.mts example.com --write  # adds and removes one TXT record
npx tsx scripts/verify-godaddy.mts example.com          # read-only
npx tsx scripts/verify-godaddy.mts example.com --write  # adds and removes one TXT record

Security notes

• Binds nothing — it's a stdio server, not a network listener.

• The Namecheap API key travels only in POST bodies and is never logged. The GoDaddy PAT travels only in an Authorization header, and config errors name the account label, never its contents.

• Route 53 arguments are passed as an argv array, never a shell string; the change batch goes on stdin.

• Money-spending and zone-destroying operations require explicit confirm / allowEmptyZone flags.

• Validates and normalises every value read back from the API before acting on it.

Licence

MIT — see LICENSE.

Credit to johnsorrentino/mcp-namecheap for the original Namecheap MCP server that inspired this one.