namecom-registrar

# Name.com Domain Registrar & DNS Manager MCP server providing nine tools for domain registration and DNS management against the **Name.com CORE API (v1)**. ## Environment Variables Set credentials before starting the server: | Variable | Required | Description | |---|---|---| | `NAMECOM_USERNAME` | Yes | Name.com account username | | `NAMECOM_TOKEN` | Yes | Name.com API token | | `NAMECOM_USERNAME_TEST` | Optional | Sandbox username (no real charges) | | `NAMECOM_TOKEN_TEST` | Optional | Sandbox API token | Generate tokens at **Account > Security > API Access**. For sandbox testing, create sandbox credentials there and set only `NAMECOM_USERNAME_TEST` and `NAMECOM_TOKEN_TEST` (leave production vars unset); the server then targets the sandbox API. ## Security & trust - **Token scope:** Authenticates via standard Name.com API token. Name.com does not currently offer per-operation token scopes; the recommended hardening is **IP whitelisting** (Account > Security > API Access) to restrict the token to your deployment environment. Use sandbox credentials during initial setup. - **Purchases:** `register_domain` enforces a **code-level human-in-the-loop gate** — it is not possible to complete a purchase without first calling `dryRun: true`. The dry-run response includes a one-time `purchaseToken` (6-digit code, valid 10 minutes, single-use, bound to the specific domain). The actual purchase call requires passing that token back; without it the tool returns an error. This is not just a documented guideline — the token gate is enforced in code. For production, **fund the account with Name.com account credit** instead of attaching a credit card when possible — that limits exposure if credentials are ever compromised. Otherwise use a payment method with spending limits or alerts. - **Install & supply chain:** This skill installs the npm package `namecom-clawbot`. The package is published with **signed npm provenance** (GitHub Actions), so you can verify on the [npm package page](https://www.npmjs.com/package/namecom-clawbot) that the build matches the [GitHub repo](https://github.com/patramsey/namecom-clawbot). Review the repo and package before installing. To limit risk, run the MCP server in an isolated environment (e.g. container or VM) and use sandbox credentials first. ## Running the Server ```bash # Install & build npm install && npm run build # Run (stdio transport — used by MCP hosts like Cursor) node dist/src/index.js ``` Or add to your MCP host config: ```json { "mcpServers": { "namecom-registrar": { "command": "node", "args": ["dist/src/index.js"], "env": { "NAMECOM_USERNAME": "<your-username>", "NAMECOM_TOKEN": "<your-api-token>" } } } } ``` ## Tools ### `check_domain` Check availability and pricing for up to 50 specific domain names at once. Returns purchase price (USD), renewal price, and premium status. **Always call this before `register_domain`** to confirm availability and get pricing for premium domains. ### `search_domain` Keyword-based domain search. Provide a keyword and optionally filter by TLDs to get suggested available domain names with pricing. Use this when the user wants to brainstorm names rather than check a specific one. ### `register_domain` Provisions and registers a domain via the account’s payment settings. Automatically enables WHOIS privacy and registrar lock. **Required confirmation flow (enforced in code):** 1. Call with **`dryRun: true`** — returns a quote (domain, years, estimated cost) plus a `purchaseToken`. No charge made. 2. Show the user the quote and get explicit confirmation. 3. Call again with **`dryRun: false`** and pass the `purchaseToken` from step 1. The `purchaseToken` is a one-time **6-digit numeric code** (e.g. `847291`) valid for 10 minutes and bound to the specific domain name — easy to relay via Telegram, WhatsApp, or read aloud. Passing an incorrect, expired, or already-used token returns an error. You cannot skip to step 3 — there is no way to complete a purchase without a valid token from a prior dry-run. For premium domains, pass the `purchasePrice` and `purchaseType` values from `check_domain`. For safety, prefer funding the Name.com account with **account credit** rather than a credit card when possible. ### `list_domains` List all domains in the account with expiration dates, autorenew/lock/privacy status. Use to see what the user already owns. ### `get_domain` Get detailed info for a single domain — contacts, nameservers, expiration, renewal pricing. ### `set_nameservers` Replace a domain's nameservers. Use when pointing a domain to Cloudflare, Route 53, Fly.io DNS, etc. ### `manage_dns` Create, delete, or list DNS records. Supported types: A, AAAA, CNAME, MX, TXT, ANAME, NS, SRV. - Use `action="list"` to see all records and get record IDs for deletion - Use `host=""` or `host="@"` for apex records, `host="*"` for wildcard - MX and SRV records require `priority` ### `solve_dns01_challenge` End-to-end ACME DNS-01 challenge workflow: 1. Creates `_acme-challenge` TXT record with the challenge digest 2. Polls Google DNS and Cloudflare DNS every 5s until global propagation (up to 2 min) 3. Cleans up the TXT record on timeout or error Returns the `recordId` so the caller can delete the record after certificate validation completes. ### `update_ddns` Dynamic DNS updater for residential/home-lab IPs: 1. Detects the machine's current public IPv4 via ipify 2. Finds the existing A record for the given host 3. Updates it if the IP changed, creates it if none exists, or skips if already correct ## Example Workflows **Find and buy a cheap .dev domain, set up a wildcard A record:** 1. `search_domain` with `keyword="coolproject"`, `tldFilter=["dev", "app"]` 2. Pick the cheapest purchasable result 3. `register_domain` with the chosen name 4. `manage_dns` → `action="create"`, `host="*"`, `type="A"`, `answer="<ip>"` **See what domains you already own and check one's details:** 1. `list_domains` to get the full inventory 2. `get_domain` with a specific domain to see contacts, nameservers, expiration **Update DDNS after IP change:** 1. `update_ddns` with `domainName="example.com"`, `host="home"` 2. Tool auto-detects the new public IP and patches the A record **Solve an ACME DNS-01 challenge for Let's Encrypt:** 1. `solve_dns01_challenge` with `domainName="example.com"`, `challengeValue="<digest>"` 2. Wait for the tool to confirm propagation 3. Complete ACME validation with the CA 4. `manage_dns` → `action="delete"`, `recordId=<id from step 1>` to clean up