namecheap-mcp

An MCP server that gives an AI agent safe, high-level control over your Namecheap domains — availability checks, registration, DNS, email forwarding, transfers, WhoisGuard privacy and account balance — over Namecheap's XML API.

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

Why this isn't a 1:1 mirror of the Namecheap API

Namecheap's API is a flat catalogue of ~40 XML commands with sharp edges. Handing those to an agent verbatim is a footgun. This server instead 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.

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.

Related MCP server: domain-suite-mcp

Tools

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

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)

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).

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 (XML parsing, error mapping, DNS engine, client, config)
npm run typecheck  # tsc --noEmit

The pure logic (XML envelope parsing, the DNS read-modify-write engine, error-code mapping, transfer status mapping, config/IP handling) is unit-tested against recorded fixture XML — no network required.

Security notes

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

• The API key travels only in POST bodies and is never logged.

• 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.