dns-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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:
Network-accessible — hosted MCP servers can serve any client, not just ones that can spawn a local subprocess.
OAuth-protected — bearer JWTs verified against Pocket ID JWKS; per-user identity available to tools via
whoami.Library-first —
dns_toolis 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.
Related MCP server: CyberMCP
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
Tool | Description |
| Server uptime, current timestamp, dns_tool version + commit hash |
| Authenticated user identity from JWT claims |
DNS
Tool | Description |
| Standard DNS lookup over DoH — 20 record types (A, AAAA, MX, TXT, NS, SOA, CNAME, PTR, SRV, CAA, DNSKEY, DS, RRSIG, NSEC, NSEC3, TLSA, SSHFP, HTTPS, SVCB, NAPTR). Optional |
| Full DNSSEC chain walk from IANA root trust anchor down to target. Real cryptographic validation at every zone cut. Returns structured |
| NSEC / NSEC3 denial-of-existence analysis — zone walkability assessment, NSEC3 hash parameters, opt-out detection |
Email security
Tool | Description |
| SPF record parsing with recursive include resolution (RFC 7208 10-lookup limit) |
| DMARC policy retrieval with organizational domain fallback |
| DKIM public key record verification for a selector + domain pair |
| Probe a domain for DKIM keys at well-known selector names; returns the selectors that resolve |
| DANE TLSA records for all MX hosts of a domain |
| Standalone TLSA record lookup at |
Threat intelligence
Tool | Description |
| IP reputation against 8 DNS-based RBLs (Spamhaus ZEN, SpamCop, UCEProtect L1/L2, Mailspike, PSBL, Barracuda, SORBS) |
| Domain reputation against DNS-based Domain Block Lists (Spamhaus DBL, URIBL, SURBL) |
| ASN lookup via Team Cymru DNS service — BGP prefix, org, country |
| Fast-flux detection — repeated A/AAAA queries to identify rotating IPs and short TTLs |
| Test a recursive resolver for tampering — NXDOMAIN wildcards, DNSSEC handling, identity |
Registration
Tool | Description |
| Domain registration data via RDAP (modern WHOIS replacement) |
Observability
Tool | Description |
| Per-tool call statistics for the current process — count, error_count, mean_ms, max_ms, first/last_called timestamps; plus session uptime and total call count. Module-level state (resets on container restart). Backed by |
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 | What it does |
| SPF, DKIM, DMARC, MTA-STS, BIMI — graded A through F with prioritized recommendations |
| Full DNSSEC chain-of-trust audit from IANA root down to target |
| Forensic phishing analysis of a raw email — TRUSTABLE / SUSPICIOUS / PHISHING / FURTHER ANALYSIS REQUIRED |
| Domain security posture audit aligned with NIST SP 800-81r3 |
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-validatedNo copy-pasting dig commands. No tab-switching. One question.
Quick Start
Prerequisites
Docker
A Pocket ID instance (>= 2.13, for Client ID Metadata Documents)
A reverse proxy with TLS termination (Caddy, nginx, etc.)
A domain name pointing at your reverse proxy
1. Pocket ID
No admin key. Register this server's resource, https://dns-mcp.example.com/mcp,
as an API (Settings → APIs) and turn on Allow all metadata document
clients. Make sure https://claude.ai/oauth/mcp-oauth-client-metadata is in
the CIMD URL allowlist, and restrict the resulting Claude client to a user
group if your Pocket ID has users who should not reach your MCP servers.
2. .env (mode 600)
POCKET_ID_BASE_URL=https://pocketid.example.com
SERVER_URL=https://dns-mcp.example.com
ALLOWED_SUBS=<your Pocket ID user id> # empty = nobody3. Deploy
git clone https://github.com/mclose/dns-mcp.git
cd dns-mcp
docker compose up -dThe 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. On
first connect Claude.ai reads this server's protected-resource metadata, finds
Pocket ID, identifies itself by its Client ID Metadata Document URL, and you
sign in with a passkey. Tool calls carry the resulting JWT; the server checks
its signature, issuer, audience (<SERVER_URL>/mcp) and sub allowlist.
Open work
Three tools from the 1.x stdio architecture are not ported into dns_tool yet:
timestamp_converter, dns_dig_style, dns_query_dot. Reference
implementations live in server.py.legacy. A port moves the function into the
right dns_tool module with library-side tests, then registers a one-line
wrapper in src/dns_mcp/server.py (make coverage-check enforces the pairing).
File structure
dns-mcp/
├── src/dns_mcp/
│ ├── __init__.py
│ ├── __main__.py # entrypoint — create_server(settings).run(transport="http")
│ ├── config.py # pydantic-settings Settings (required URLs, ALLOWED_SUBS)
│ ├── auth.py # fastmcp JWTVerifier + fail-closed sub allowlist
│ ├── tracking.py # per-call JSON log lines + session stats
│ └── server.py # fastmcp app: 25 tools + 4 prompts + /health
├── prompts/ # MCP analyst prompt text files
├── tests/ # pytest (auth, schema, annotations, tracking, prompts)
├── 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 # floors + dns_tool URL pin; exact versions in uv.lock
├── uv.lock
└── Makefile # install/check/build/deploy/bump-dns_toolDay-to-day
Command | What it does |
| Rebuild the Docker image |
| Full clean build, no cache |
|
|
| Build image, run |
| Interactive shell inside the container |
| Push to GitHub + VPS post-receive hook |
| Tail container logs |
| Container status |
Security
No shell execution — all DNS via
dns_tool(dnspython internally), RDAP viarequestsOAuth bearer JWT verification against Pocket ID JWKS on every tool call
Pydantic
Fieldconstraints enforced at MCP boundary — invalid input rejected before reachingdns_toolNon-root container user (
claude, uid 1000)SPF recursion limit enforced (RFC 7208)
RDAP: 10s timeout, max 3 redirects
License
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Domain intel for AI agents: RDAP registration, DNS, email deliverability, tech stack.
Domain intel for AI agents: RDAP registration, DNS, email deliverability, tech stack.
Free SPF, DKIM, DMARC, blacklist, MX and bounce checks for any domain, as MCP tools for AI agents.
A domain's DNS records and RDAP registration per call for AI agents. Paid per domain, no run.
1
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server for domain intelligence — WHOIS, DNS records, SSL certificate inspection, SPF/DMARC validation, security-header audits, and blacklist/reputation checks, callable by AI agents. Powered by domainintel.app; runs server-side, no local setup.771 npmMIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to perform cybersecurity analysis including RDAP lookup, DNS analysis, SSL inspection, security header detection, and more, returning structured security reports.-
- FlicenseNot gradedqualityBmaintenanceConnects DMARC monitoring data to AI assistants, enabling natural language queries about domain compliance, sender analysis, and email authentication issues.8-
- AlicenseAqualityBmaintenanceEnables AI assistants and agents to query domain intelligence, including registered domains across 1,584 TLDs, new and deleted domains, DNS providers, registrars, popularity rankings, and compromised domains/IPs through MCP tools.91MIT