DNS MCP Server

DNS MCP Server

Real-time DNS security analysis for AI assistants via MCP. Gives your assistant the ability to investigate domains the way a practitioner would — DNSSEC chain validation, email authentication posture, and registration intelligence — without leaving your chat session.

Built by a cybersecurity professional for SOC investigation workflows. Not a toy — the same queries you would run at the command line, accessible through any MCP-compatible assistant in real time.

Architecture (2.0.0)

dns-mcp is a Streamable HTTP MCP server with OAuth via Pocket ID. Tool implementations are thin wrappers around the dns_tool Python library, which owns all DNS logic. The server itself is ~430 lines of code: auth bootstrap, tool registration, and prompt loading.

Claude.ai / Claude Code / any MCP client
              │
              │ Streamable HTTP + OAuth bearer (JWT)
              ▼
       Caddy reverse proxy           (TLS, DNS-01 / Let's Encrypt)
              │
              ▼
     dns-mcp container               (FastMCP, OAuth verifier)
              │
              ▼
        dns_tool library             (DoH client, validators, parsers)
              │
              ▼
   doh.lab.deflationhollow.net      (Unbound DoH resolver, optional)

Three benefits over the previous stdio-only architecture:

1. Network-accessible — hosted MCP servers can serve any client, not just ones that can spawn a local subprocess.
2. OAuth-protected — bearer JWTs verified against Pocket ID JWKS; per-user identity available to tools via whoami.
3. Library-first — dns_tool is published independently and reusable. The same code powers a CLI, this MCP server, and (eventually) a REST API.

The old stdio architecture lives at server.py.legacy for porting reference. The remote branch (mcp-shim Go bridge) is deprecated.

Tools

dns-mcp 2.0.0 currently exposes 19 tools. Ten additional tools from the 1.x stdio architecture are pending port into dns_tool — see Open work.

Meta

DNS

Email security

Threat intelligence

Registration

Observability

Downstream consumers (e.g. ~/projects/yahoo batch forensics) call session_stats as the final tool in each investigation to record which DNS tools were consulted; an empty stats dict indicates a "cold read" where the analyst LLM produced a verdict without DNS verification.

Tool descriptors

All 19 tools use Pydantic Field for parameter descriptors. The LLM sees:

• Per-parameter descriptions explaining what the parameter means
• Literal[...] enums for record types and protocols (no string-guessing)
• Regex patterns validating FQDN syntax, IPv4 dotted-quad, DKIM selector format
• Length and range constraints (port 1–65535, FQDN max 253 chars, etc.)

Constraints are advertised in the tool descriptor JSON Schema and enforced at the MCP boundary by FastMCP — invalid input is rejected before dns_tool is called. See src/dns_mcp/server.py for the type alias definitions.

Analyst Prompts

Four analyst prompt templates ship with the server. Any MCP-compatible client that supports prompts can list and invoke them.

Prompt invocation requires client-side UI support. Claude Code surfaces them as /mcp__dns-mcp__<prompt_name>. Claude.ai web exposes prompts via the slash-command picker. Use tools ad-hoc in clients that do not support prompts.

Example

Ask your assistant: "Check the email security posture of example.com"

The assistant calls check_spf, check_dmarc, check_dane in sequence and returns a complete analysis:

✅ SPF:     Hard fail (-all), 3 lookups (under RFC limit)
✅ DMARC:   p=reject, pct=100 — full enforcement, aggregate reporting configured
✅ DANE:    TLSA records present and DNSSEC-validated

No copy-pasting dig commands. No tab-switching. One question.

Quick Start

Prerequisites

• Docker
• A Pocket ID instance (or any OIDC provider supporting Dynamic Client Registration)
• A reverse proxy with TLS termination (Caddy, nginx, etc.)
• A domain name pointing at your reverse proxy

1. Pocket ID

Mint an admin API key in Pocket ID's UI: Settings → API Keys → Create new key. Name it dns-mcp so you can revoke just this service if needed. Copy the key value (it is shown once).

2. .env

POCKET_ID_BASE_URL=https://pocketid.example.com
POCKET_ID_API_KEY=<the key from step 1>
SERVER_URL=https://dns-mcp.example.com

3. Deploy

git clone https://github.com/mclose/dns-mcp.git
cd dns-mcp
docker compose up -d

The image installs dns_tool as a versioned dependency (URL-pinned in pyproject.toml); make build is also available for direct development.

4. Reverse proxy

The container listens on port 8000 (HTTP). Front it with TLS termination:

dns-mcp.example.com {
    reverse_proxy dns-mcp:8000 {
        flush_interval -1   # required for Streamable HTTP / SSE
    }
}

If you use mclose/gateway (the Caddy + DNS-01 setup that serves dns-mcp.lab.deflationhollow.net), drop a conf.d/dns-mcp.conf matching the existing pattern.

5. Connect

Add https://dns-mcp.example.com/mcp as a connector in your MCP client. The OAuth flow runs once on first connect — Claude.ai redirects to Pocket ID, you authenticate, the server creates a DCR client on your Pocket ID instance, and returns a JWT. Subsequent tool calls send that JWT as a bearer token; the server verifies against Pocket ID JWKS.

Open work

Eleven tools from the 1.x stdio architecture are not yet ported into dns_tool and are therefore not registered in 2.0.0:

• check_caa (with CNAME chain tracing and wildcard delegation detection)
• check_zone_transfer (AXFR enumeration)
• check_bimi, check_mta_sts, check_smtp_tlsrpt
• check_ct_logs (Certificate Transparency log enumeration via crt.sh)
• timestamp_converter, reverse_dns
• enumerate_dkim_selectors, dns_dig_style, dns_query_dot

Reference implementations live in server.py.legacy. Each port involves moving the function into the appropriate dns_tool module (dns_tool.email, dns_tool.intel, etc.), adding tests on the library side, and registering a one-line wrapper in src/dns_mcp/server.py.

File structure

dns-mcp/
├── src/dns_mcp/
│   ├── __init__.py
│   ├── __main__.py            # entrypoint — create_server().run(transport="streamable-http")
│   ├── config.py              # pydantic-settings Settings class
│   ├── auth.py                # JWKSTokenVerifier + JWTAccessToken
│   └── server.py              # FastMCP app: OAuth routes + 16 tools + 4 prompts (~430 lines)
├── prompts/                   # MCP analyst prompt text files
├── tests/                     # pytest unit tests (legacy — pending rewrite)
├── tools/                     # operator scripts (smoke tests, deploy helpers)
├── server.py.legacy           # 1.x stdio server (5,095 lines), reference for 11 deferred tool ports
├── compose.yaml
├── Dockerfile
├── pyproject.toml             # dns_tool URL-pinned to dist tarball
└── Makefile                   # build/lint/import-check

Day-to-day

Security

• No shell execution — all DNS via dns_tool (dnspython internally), RDAP via requests
• OAuth bearer JWT verification against Pocket ID JWKS on every tool call
• Pydantic Field constraints enforced at MCP boundary — invalid input rejected before reaching dns_tool
• Non-root container user (claude, uid 1000)
• SPF recursion limit enforced (RFC 7208)
• RDAP: 10s timeout, max 3 redirects

License

MIT