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__ . 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= 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