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.

Tools

Tool	Kind	What it does
check_domain_availability	read	Batch-check availability + premium pricing for up to 50 domains in one call.
get_domain_pricing	read	List-price lookup per TLD for register / renew / transfer / reactivate.
list_domains	read	Paged, filterable list of domains in the account.
get_domain_info	read	One coherent view of a domain: dates, registrar lock, privacy, DNS, nameservers.
register_domain	paid · confirm	Register a domain. Dry-runs unless confirm: true; guides on extended attributes.
renew_domain	paid · confirm	Renew a domain for N years.
reactivate_domain	paid · confirm	Reactivate a recently-expired domain (redemption).
set_domain_lock	write (idempotent)	Lock / unlock the registrar transfer lock.
get_dns_records	read	Read the current host records; warns if the domain isn't on Namecheap DNS.
modify_dns_records	write	Safe add/update/delete of host records via read-modify-write.
replace_all_dns_records	destructive · confirm	Replace the entire zone with an explicit record set.
get_nameservers	read	Read the domain's nameservers and whether it uses Namecheap DNS.
set_nameservers	write	Set custom nameservers, or revert to Namecheap default DNS.
get_email_forwarding	read	Read email-forwarding rules.
set_email_forwarding	write	Upsert (merge) or replace forwarding rules.
transfer_domain	paid · confirm	Start an inbound transfer; explains the EPP/auth-code requirement.
get_transfer_status	read	Poll a transfer, mapping the numeric StatusID to meaning + phase.
get_account_balance	read	Account balances and funds available for auto-renew.
get_domain_privacy	read	WhoisGuard / domain privacy subscription status.
set_domain_privacy	write	Enable (with a forwarding email) or disable WhoisGuard privacy.

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

Variable	Required	Default	Notes
NAMECHEAP_API_USER	yes	—	API username (Profile → Tools → API Access).
NAMECHEAP_API_KEY	yes	—	API key from the same screen. Kept out of all logs.
NAMECHEAP_USERNAME	no	= API_USER	Account the commands act on; usually identical.
NAMECHEAP_CLIENT_IP	no	auto-detect	Public IPv4 the requests come from. Auto-detected via api.ipify.org if unset — but the address still has to be whitelisted.
NAMECHEAP_SANDBOX	no	false	true → use the sandbox API (separate sandbox credentials).
NAMECHEAP_TIMEOUT_MS	no	30000	Per-request network timeout (clamped 1000–120000).

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.