Skip to main content
Glama

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.

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

ping

Server uptime, current timestamp, dns_tool version + commit hash

whoami

Authenticated user identity from JWT claims

DNS

Tool

Description

dns_query

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 subnet sends an EDNS Client Subnet hint (RFC 7871); the ecs block says whether the answer was really tailored to it

dnssec_validate

Full DNSSEC chain walk from IANA root trust anchor down to target. Real cryptographic validation at every zone cut. Returns structured verdict + per-zone findings + event transcript

nsec_info

NSEC / NSEC3 denial-of-existence analysis — zone walkability assessment, NSEC3 hash parameters, opt-out detection

Email security

Tool

Description

check_spf

SPF record parsing with recursive include resolution (RFC 7208 10-lookup limit)

check_dmarc

DMARC policy retrieval with organizational domain fallback

check_dkim

DKIM public key record verification for a selector + domain pair

enumerate_dkim_selectors

Probe a domain for DKIM keys at well-known selector names; returns the selectors that resolve

check_dane

DANE TLSA records for all MX hosts of a domain

check_tlsa

Standalone TLSA record lookup at _<port>._<proto>.<host>

Threat intelligence

Tool

Description

check_rbl

IP reputation against 8 DNS-based RBLs (Spamhaus ZEN, SpamCop, UCEProtect L1/L2, Mailspike, PSBL, Barracuda, SORBS)

check_dbl

Domain reputation against DNS-based Domain Block Lists (Spamhaus DBL, URIBL, SURBL)

cymru_asn

ASN lookup via Team Cymru DNS service — BGP prefix, org, country

check_fast_flux

Fast-flux detection — repeated A/AAAA queries to identify rotating IPs and short TTLs

detect_hijacking

Test a recursive resolver for tampering — NXDOMAIN wildcards, DNSSEC handling, identity

Registration

Tool

Description

rdap_lookup

Domain registration data via RDAP (modern WHOIS replacement)

Observability

Tool

Description

session_stats

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 dns_mcp/tracking.py.

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

email_security_audit

SPF, DKIM, DMARC, MTA-STS, BIMI — graded A through F with prioritized recommendations

dnssec_chain_audit

Full DNSSEC chain-of-trust audit from IANA root down to target

soc_email_forensics

Forensic phishing analysis of a raw email — TRUSTABLE / SUSPICIOUS / PHISHING / FURTHER ANALYSIS REQUIRED

nist_800_81r3_audit

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-validated

No 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 = nobody

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. 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_tool

Day-to-day

Command

What it does

make build

Rebuild the Docker image

make rebuild

Full clean build, no cache

make lint

pre-commit run --all-files (ruff check + format)

make import-check

Build image, run create_server() inside, assert tools register

make shell

Interactive shell inside the container

make deploy

Push to GitHub + VPS post-receive hook

make logs

Tail container logs

make status

Container status

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An 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.
      7
      71 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to perform cybersecurity analysis including RDAP lookup, DNS analysis, SSL inspection, security header detection, and more, returning structured security reports.
      -
    • F
      license
      Not graded
      quality
      B
      maintenance
      Connects DMARC monitoring data to AI assistants, enabling natural language queries about domain compliance, sender analysis, and email authentication issues.
      8
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      9
      1
      MIT