DNS MCP Server

io.github.mclosePublished by GitHub account mclosev1.3.4Updated Oct 24, 2026

Real-time DNS security analysis — DNSSEC, email auth, and RDAP. Built for SOC investigations.

VerifiedSTDIODesktop onlyWeb Search & ScrapingSecurity & Monitoring

Overview

AI-generated overview

A DNS security analysis server that lets an assistant run DNSSEC, email authentication, reputation and registration lookups on domains.

What you can do
Run DNS queries over DoH across many record types, with optional client-subnet hints and resolver-tampering checks for hijacking detection. Validate DNSSEC chains from the IANA root and analyze NSEC/NSEC3 denial of existence. Audit email authentication: SPF, DMARC, DKIM selectors, DANE and TLSA records. Check IP and domain reputation against DNS blocklists, look up ASN and BGP data, and detect fast-flux rotation. Retrieve domain registration data via RDAP, and read or reset per-session tool-call statistics.
When to use it
Useful for security analysts and SOC investigations that need domain posture checks, phishing triage, or DNSSEC and email authentication audits without leaving the chat. Also handy for ad-hoc DNS reconnaissance during incident response.
Requirements
Runs as a local Docker container over stdio, but the README describes a Streamable HTTP deployment needing Docker, a Pocket ID or other OIDC provider, a TLS reverse proxy and a domain name. Environment variables POCKET_ID_BASE_URL, POCKET_ID_API_KEY and SERVER_URL are set in a .env file. Outbound DNS-over-HTTPS and RDAP network access is required.
Before you install
The README's deployment path requires a Pocket ID admin API key (POCKET_ID_API_KEY), which is shown once and should be revocable; keep it out of shared files. Queries go to third-party DNS resolvers, blocklists, Team Cymru and RDAP services, so investigated domain names are disclosed externally. Tools are read-only lookups, but reset_stats clears session statistics.

Installation

In SourceWeft

  1. Open DNS MCP Server in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

ToolDescription
pingServer uptime, current timestamp, dns_tool version + commit hash
whoamiAuthenticated user identity from JWT claims

DNS

ToolDescription
dns_queryStandard 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_validateFull 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_infoNSEC / NSEC3 denial-of-existence analysis — zone walkability assessment, NSEC3 hash parameters, opt-out detection

Email security

ToolDescription
check_spfSPF record parsing with recursive include resolution (RFC 7208 10-lookup limit)
check_dmarcDMARC policy retrieval with organizational domain fallback
check_dkimDKIM public key record verification for a selector + domain pair
enumerate_dkim_selectorsProbe a domain for DKIM keys at well-known selector names; returns the selectors that resolve
check_daneDANE TLSA records for all MX hosts of a domain
check_tlsaStandalone TLSA record lookup at _<port>._<proto>.<host>

Threat intelligence

ToolDescription
check_rblIP reputation against 8 DNS-based RBLs (Spamhaus ZEN, SpamCop, UCEProtect L1/L2, Mailspike, PSBL, Barracuda, SORBS)
check_dblDomain reputation against DNS-based Domain Block Lists (Spamhaus DBL, URIBL, SURBL)
cymru_asnASN lookup via Team Cymru DNS service — BGP prefix, org, country
check_fast_fluxFast-flux detection — repeated A/AAAA queries to identify rotating IPs and short TTLs
detect_hijackingTest a recursive resolver for tampering — NXDOMAIN wildcards, DNSSEC handling, identity

Registration

ToolDescription
rdap_lookupDomain registration data via RDAP (modern WHOIS replacement)

Observability

ToolDescription
session_statsPer-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.
reset_statsClear all tool-call statistics and restart the session clock.

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.

PromptWhat it does
email_security_auditSPF, DKIM, DMARC, MTA-STS, BIMI — graded A through F with prioritized recommendations
dnssec_chain_auditFull DNSSEC chain-of-trust audit from IANA root down to target
soc_email_forensicsForensic phishing analysis of a raw email — TRUSTABLE / SUSPICIOUS / PHISHING / FURTHER ANALYSIS REQUIRED
nist_800_81r3_auditDomain 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 (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

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

3. Deploy

bash
git clone https://github.com/mclose/dns-mcp.gitcd dns-mcpdocker 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:

caddy
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

CommandWhat it does
make buildRebuild the Docker image
make rebuildFull clean build, no cache
make lintpre-commit run --all-files (ruff check + format)
make import-checkBuild image, run create_server() inside, assert tools register
make shellInteractive shell inside the container
make deployPush to GitHub + VPS post-receive hook
make logsTail container logs
make statusContainer 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

Source: README.md at commit e6e6cde

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.3.4LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.