Cloudflare Domains Toolkit

Cloudflare Domains Toolkit contains two focused local tools:

1. Cloudflare Domain MCP lets an AI search, check, quote, and register a domain through Cloudflare Registrar. A person must approve the exact domain and live price before the billable call.
2. Cloudflare Domains CLI lists zones and manages DNS records after a domain is on Cloudflare.

Both tools are client-neutral, open source, and designed to keep Cloudflare API tokens outside the project folder.

Current release: 1.0.1 (1.0.1 in both package manifests).

What you get

• a standard local stdio MCP server
• domain search and authoritative availability checks
• exact registration quotes that expire after five minutes
• standard MCP human approval during a purchase
• a hard $20 maximum for the complete initial domain charge
• a second availability, price, and term check before approval
• a companion cf-domains DNS command-line tool
• confirmation before interactive DNS deletion
• macOS login Keychain support
• environment-variable support for other systems
• Cursor, Codex, and generic MCP client examples
• automated unit tests and an MCP smoke test
• beginner setup guides and technical architecture notes
• the complete creation story and a real MCP purchase-approval screenshot

safety limit happen to be the same amount. They are separate controls.

Start here

Read these files in order:

1. WHY.md explains why the bundle contains both MCP and CLI tools.
2. BUILDING.md tells the complete story of how I created and verified it.
3. CONFIGURATION.md explains the two least-privilege Cloudflare tokens.
4. ARCHITECTURE.md shows how each request moves through the code.
5. SECURITY.md explains the financial and DNS safety boundaries.

Each tool also has a focused guide:

• code/mcp/README.md
• code/cli/README.md

Quick verification

Verify the MCP server:

cd code/mcp
npm install
npm run check
npm test
npm run smoke

Verify the DNS CLI:

cd ../cli
npm install
npm run check
npm test

The automated tests use fakes and placeholder credentials. They do not buy a domain or change DNS.

Requirements

• Node.js 20 or newer
• a Cloudflare account
• a Registrar-capable Cloudflare account for domain purchases
• two narrowly scoped API tokens: one for Registrar and one for DNS
• a default payment method and registrant contact for Registrar
• an MCP client with stdio support
• MCP form elicitation support for AI-assisted purchases
• macOS for Keychain storage, or another local secret provider

Cloudflare currently describes the Registrar API as beta. Supported extensions and API behavior can change.

Project structure

├── code/
│   ├── mcp/              Domain discovery and guarded registration server
│   └── cli/              Zone and DNS record command-line tool
├── screenshots/          Real MCP purchase-approval example
├── AGENTS.md             Rules for AI coding agents
├── ARCHITECTURE.md       Components and request flows
├── BUILDING.md           Complete creation and verification story
├── CHANGELOG.md          Release history
├── CONFIGURATION.md      Cloudflare, secret, and client setup
├── CUSTOMIZATION.md      Safe extension ideas
├── DECISIONS.md          Why the project works this way
├── DEPLOYMENT.md         Local installation and distribution
├── SECURITY.md           Threat model and safety invariants
└── WHY.md                Product rationale

License

MIT. You can use, modify, and redistribute the source. Keep the license notice with substantial copies.

The bundle contains two local programs with independent package manifests, dependencies, token storage entries, and Cloudflare permissions.

flowchart TD
  ai["AI client"] -->|MCP tools + approval| server["MCP server"]
  server --> service["Registrar service"] --> registrar["Cloudflare Registrar API"]

  operator["Person or AI tool"] -->|cf-domains commands| cli["DNS CLI"]
  cli --> adapter["Cloudflare adapter"] --> dns["Cloudflare Zones + DNS API"]

  classDef entry fill:#332d23,stroke:#e8a830,stroke-width:2px,color:#f0e4cc
  classDef core fill:#c85520,stroke:#e8a830,stroke-width:2px,color:#fff8ea
  classDef service fill:#2d2a25,stroke:#a87628,color:#f0e4cc
  classDef external fill:#211f1c,stroke:#5b5143,color:#d2c4aa

  class ai,operator entry
  class server,cli core
  class service,adapter service
  class registrar,dns external

Neither program opens a local network port. The MCP server communicates over stdio. The CLI runs one command and exits.

Registrar MCP layer

code/mcp/src/server.ts creates the MCP server and registers four typed tools:

• search_domains
• check_domain_availability
• quote_domain_purchase
• purchase_domain

Zod validates tool arguments. MCP annotations mark discovery tools as read-only and registration as destructive. The same layer sends the standard MCP elicitation request containing the exact domain, price, term, and warning.

Registrar service layer

code/mcp/src/service.ts owns the purchase policy. It normalizes domains, creates and stores quotes, enforces exact matching, recalculates live pricing, requests approval, and finally calls the registration adapter.

Because this layer does not know about JSON-RPC or HTTP, tests can use a fake Registrar client and a fake approval callback.

Registrar API adapter

code/mcp/src/cloudflare.ts owns Cloudflare HTTPS requests: search, authoritative availability checks, extension metadata, and registration.

config.ts reads the account ID and Registrar token. domain.ts validates ASCII domain names. money.ts converts decimal USD strings to integer cents so the purchase boundary never relies on floating-point arithmetic.

Availability flow

flowchart LR
  request["Availability request"] --> tool["check_domain_availability"]
  tool --> validate["Validate exact domain"]
  validate --> registry["Check registry availability<br/>and live pricing"]
  registry --> result["Return read-only result"]

  classDef entry fill:#332d23,stroke:#e8a830,stroke-width:2px,color:#f0e4cc
  classDef core fill:#c85520,stroke:#e8a830,stroke-width:2px,color:#fff8ea
  classDef step fill:#2d2a25,stroke:#a87628,color:#f0e4cc
  classDef output fill:#211f1c,stroke:#5b5143,color:#d2c4aa

  class request entry
  class tool core
  class validate,registry step
  class result output

No quote or mutable state is created.

Purchase flow

flowchart TD
  quote["quote_domain_purchase"] --> check["Authoritative availability<br/>and pricing check"]
  check --> guard["Reject premium,<br/>non-USD, or over $20"]
  guard --> term["Read minimum term<br/>and total initial charge"]
  term --> saved["Store five-minute quote"]

  saved --> purchase["purchase_domain"]
  purchase --> match["Match quote ID, domain,<br/>currency, and cents"]
  match --> recheck["Recheck availability,<br/>price, and term"]
  recheck --> unchanged{"Anything changed?"}
  unchanged -->|Yes| newquote["Reject and require<br/>a new quote"]
  unchanged -->|No| approval["Request human approval"]
  approval --> used["Mark quote used"] --> register["Register domain"]

  classDef entry fill:#332d23,stroke:#e8a830,stroke-width:2px,color:#f0e4cc
  classDef core fill:#c85520,stroke:#e8a830,stroke-width:2px,color:#fff8ea
  classDef step fill:#2d2a25,stroke:#a87628,color:#f0e4cc
  classDef decision fill:#4a3824,stroke:#e8a830,stroke-width:2px,color:#f0e4cc
  classDef stop fill:#321f1c,stroke:#c85520,color:#f0e4cc
  classDef output fill:#211f1c,stroke:#5b5143,color:#d2c4aa

  class quote,purchase entry
  class check,guard,term,match,recheck,approval,used step
  class saved core
  class unchanged decision
  class newquote stop
  class register output

Quotes live in an in-memory Map. Restarting the MCP process invalidates them. The quote is marked used before registration to prevent an automatic retry when a network failure leaves Cloudflare's final state unclear.

DNS CLI command layer

code/cli/src/cli.js defines commands with Commander and interactive prompts with Prompts. It parses flags, prints tables, and requires confirmation before deletion unless --yes is explicitly passed.

DNS API adapter

code/cli/src/cloudflare.js finds the exact zone, handles pagination, normalizes record names, builds allow-listed request bodies, and reports Cloudflare API errors.

The client accepts an injected fetch implementation, which lets tests inspect requests without network access.

code/cli/src/keychain.js reads the DNS token from the process environment or the macOS login Keychain.

DNS change flow

flowchart LR
  command["cf-domains update"] --> token["Read DNS token"]
  token --> zone["Find exact zone"]
  zone --> patch["Build allow-listed<br/>PATCH body"]
  patch --> api["Send to Cloudflare"]
  api --> result["Print updated record"]

  classDef entry fill:#332d23,stroke:#e8a830,stroke-width:2px,color:#f0e4cc
  classDef core fill:#c85520,stroke:#e8a830,stroke-width:2px,color:#fff8ea
  classDef step fill:#2d2a25,stroke:#a87628,color:#f0e4cc
  classDef output fill:#211f1c,stroke:#5b5143,color:#d2c4aa

  class command entry
  class token,zone,patch step
  class api core
  class result output

Create and update requests allow-list supported fields. Unexpected CLI values are not copied into the Cloudflare request body.