DNS Doctor — Claude Code plugin & DNS skill (DMARC, SPF, DKIM)

Diagnose and fix a domain's email authentication (SPF, DMARC, DKIM, MX, blacklist, domain/SSL expiry) from inside Claude. This plugin bundles the DNS Doctor skill (the scan → diagnose → fix workflow) and an MCP server config pointing at the hosted DNS Doctor tools.

The moat: every fix record you get back is generated and validated by a deterministic engine — RFC grammar plus the SPF 10-lookup counter — never an LLM guess. Your agent hands the human a record that already parses correctly, not a plausible-looking string that silently fails.

What's inside

claude-plugin/
├── .claude-plugin/plugin.json   # plugin manifest
├── .mcp.json                    # MCP server: https://dnsdoctor.dev/mcp (HTTP)
├── skills/dns-doctor/SKILL.md   # the scan → diagnose → fix workflow
├── src/                         # @dnsdoctor/mcp — the local stdio MCP server
├── tools.json                   # the 15 tool definitions (generated, never hand-edited)
├── instructions.txt             # the server's own `initialize` guidance (generated)
├── tests/                       # vitest suite for the stdio server
├── package.json  tsconfig.json  # npm package + build
├── LICENSE                      # Apache-2.0
└── README.md

Tools

The two monitoring reads are listed for everyone and callable with a token: they appear in the tool list on both transports, and without a valid token the call is refused with the page the account owner mints one on. Over the hosted HTTP transport the dnsdoctor://domains resource (your monitored domains) is likewise always listed and refused without a token; the local stdio server registers the tools only — no resource. Anonymous access covers all thirteen diagnosis tools, which is enough for a one-off diagnosis either way.

Install

Claude Code

Add the marketplace/repo and enable the plugin:

/plugin marketplace add dnsdoctor/claude-plugin
/plugin install dns-doctor

Public home: github.com/dnsdoctor/claude-plugin (org dnsdoctor, domain-verified). The plugin is developed in the DNS Doctor monorepo and published here as clean release snapshots.

Or point Claude Code at a local checkout of this directory during development. Once enabled, the skill auto-loads and the dns-doctor MCP server connects to https://dnsdoctor.dev/mcp.

claude.ai (MCP connector)

Add a custom connector with:

• URL: https://dnsdoctor.dev/mcp
• Transport: Streamable HTTP
• Auth: none (anonymous) — or a Bearer token (below)

Any MCP client (standard config)

{
  "mcpServers": {
    "dns-doctor": {
      "url": "https://dnsdoctor.dev/mcp"
    }
  }
}

Optional: API token for monitored domains

Anonymous access covers scanning and fixes. A per-account API token unlocks the account's own monitoring data: the get_alerts and get_readiness tools, and the dnsdoctor://domains resource (your continuously-monitored domains and their latest per-check statuses).

1. Sign in at https://dnsdoctor.dev → Settings → API tokens → create a token. The plaintext (dnsd_…) is shown once; copy it.

2. Add the Authorization header to the server in .mcp.json:

   config.json

   Copy

   {
     "mcpServers": {
       "dns-doctor": {
         "type": "http",
         "url": "https://dnsdoctor.dev/mcp",
         "headers": { "Authorization": "Bearer ${DNSDOCTOR_API_TOKEN}" }
       }
     }
   }
   

   Then export DNSDOCTOR_API_TOKEN=dnsd_YOUR_TOKEN in your environment. Never commit the token.

Transport

Two supported public transports, same 15 tools:

• Hosted streamable HTTP — https://dnsdoctor.dev/mcp, wired in this plugin's .mcp.json. No install, no keys.
• Local stdio — npx -y @dnsdoctor/mcp. A thin server that runs on your machine and calls the public DNS Doctor REST API; it holds no diagnosis logic of its own and relays every record string verbatim.

{
  "mcpServers": {
    "dns-doctor": {
      "command": "npx",
      "args": ["-y", "@dnsdoctor/mcp"],
      "env": { "DNSDOCTOR_API_TOKEN": "dnsd_YOUR_TOKEN" }
    }
  }
}

DNSDOCTOR_API_TOKEN is optional (anonymous access covers scanning and fixes; the two monitoring reads need it). DNSDOCTOR_API_BASE overrides the origin — it must be an origin that serves the /api/… paths, i.e. the public site rather than a bare backend port.

Build the stdio server from source

npm ci
npm test
npm run build      # -> dist/index.js, the package's bin entrypoint

tools.json and instructions.txt are generated from the hosted server and pinned by a backend test — never hand-edit them, and never add a tool description to src/. Both files ship in the npm tarball; without them the client has no tools and none of its safety guidance.

Worked example

You: Our invoices keep landing in customers' spam. Domain is example.com.

Claude (scan_domain → example.com): DMARC is at p=none, so nothing enforces alignment — receivers can't tell your mail from a spoof. SPF passes with 7 of 10 lookups used. DKIM: a selector was found and is valid. Not blacklisted. Domain expires in 240 days.

Claude (build_dmarc_upgrade → example.com): SPF is aligned and DKIM is present, so enforcement to p=reject is safe. Publish this exact TXT record at _dmarc.example.com — paste it verbatim, don't edit it:

Code

Copy

v=DMARC1; p=reject; rua=mailto:dmarc@example.com; adkim=r; aspf=r

Apply it in your DNS host once you've confirmed it's approved, then ask me to re-scan to verify. Want the domain watched continuously with aggregate-report alerts? I can send a setup link to your email.

Learn more

• Methodology (how the verdicts are computed): https://dnsdoctor.dev/methodology
• REST API / OpenAPI schema: https://dnsdoctor.dev/api/v1/openapi.json

License

Apache-2.0 — see LICENSE.