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'd run at the command line, accessible through any MCP-compatible assistant in real time.

Tools

DNS Tools

Email Security Tools

Threat Intelligence

Utility

Resources

Three reference resources are available to MCP clients that support resource reading. They cover tool-specific output vocabulary that a client AI cannot infer from tool schemas alone — field meanings, status codes, and RBL return codes specific to this server's output format.

Resources are pull-based — clients load them on demand, not on every message.

Analyst Prompts

The server ships with four analyst prompt templates. Any MCP-compatible client can list and invoke them — no Claude-specific configuration required.

Prompts set the analyst context and tool-use strategy for the session. The LLM runs the appropriate tools in sequence and synthesizes a structured report.

Client support note: MCP prompt invocation requires client-side UI support. Claude Code CLI supports prompts via slash commands (see Quick Start §4). Claude Desktop currently exposes MCP tools only — prompts are registered but not reachable from the UI. Use tools ad-hoc in Desktop, or describe the analysis you want and the model will apply the same workflow.

Example

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

The assistant calls check_spf, check_dmarc, check_dane, check_mta_sts, and check_bimi 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
⚠️  MTA-STS: Not configured — no TLS enforcement policy published
⚠️  BIMI: Not configured

Overall: B+ — Strong fundamentals, two actionable gaps identified.

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

Quick Start

Prerequisites

• Docker

1. Build

git clone https://github.com/mclose/dns-mcp.git
cd dns-mcp
make build

2. Connect

Any MCP client that supports stdio transport works. The server config block is the same across all clients — see Client Support for client-specific setup instructions and config file locations.

The --dns 9.9.9.9 flag ensures DNSSEC-correct resolution regardless of the host's DNS configuration.

3. Verify

make test                  # unit tests inside container
./test-mcp-stdio.sh        # end-to-end stdio test

4. Start an analysis

Once connected, just ask:

"Check the email security posture of deflationhollow.net" "Audit the DNSSEC chain for dnssec.works" "Is this email headers trustworthy?" (paste raw headers) "Run a NIST SP 800-81r3 security audit on example.com"

Clients that support MCP prompts can also invoke the structured analyst workflows directly — see Client Support for details.

Client Support

All clients use the same server block. The command and args are identical everywhere — only the config file location and prompt invocation differ.

{
  "mcpServers": {
    "dns-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--dns", "9.9.9.9", "dns-mcp", "python", "server.py"]
    }
  }
}

Optional: Spamhaus DQS key

check_rbl queries zen.spamhaus.org by default. This works for occasional analyst use, but Spamhaus rate-limits or blocks queries from resolvers without a service agreement. When this happens, Spamhaus returns administrative codes (127.255.255.252–255) that the tool detects and surfaces as an error on that RBL entry — not a false listing — with a message explaining the cause.

For reliable, unrestricted access, set your free Spamhaus Data Query Service key via the SPAMHAUS_DQS_KEY environment variable — the tool will automatically switch to the DQS zone:

{
  "mcpServers": {
    "dns-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--dns", "9.9.9.9", "-e", "SPAMHAUS_DQS_KEY", "dns-mcp", "python", "server.py"],
      "env": { "SPAMHAUS_DQS_KEY": "your-key-here" }
    }
  }
}

Claude Desktop

Prompts: Not supported — Desktop exposes MCP tools only. Use ad-hoc questions.

Config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Claude Code CLI

Prompts: Full support via / slash commands.

Add the server with one command (adds to local project config):

claude mcp add dns-mcp -- docker run --rm -i --dns 9.9.9.9 dns-mcp python server.py

Or add --scope user to make it available across all projects. Invoke prompts by typing / in the chat — the four analyst prompts appear as:

/mcp__dns-mcp__email_security_audit
/mcp__dns-mcp__dnssec_chain_audit
/mcp__dns-mcp__soc_email_forensics
/mcp__dns-mcp__nist_800_81r3_audit

Type /mcp__dns-mcp__ and tab-complete to see all four.

Gemini CLI

Prompts: Supported (Gemini CLI implements the full MCP spec).

Add the server with one command:

gemini mcp add dns-mcp -- docker run --rm -i --dns 9.9.9.9 dns-mcp python server.py

Or add manually to ~/.gemini/settings.json (user scope) or .gemini/settings.json (project scope) using the same JSON block above.

Cursor

Prompts: Verify with your installed version — Cursor MCP support is active and evolving. Config location: consult Cursor MCP docs.

Add the JSON block above to your Cursor MCP config file.

VS Code (GitHub Copilot / Continue / Cline)

Prompts: Depends on the extension — check extension documentation.

Config location varies by extension. The JSON block above is the standard stdio format; consult your extension's MCP setup guide for the exact file path.

Zed

Prompts: Check current Zed release notes — MCP support is active. Config location: consult Zed MCP docs.

Windsurf

Prompts: Check current Windsurf release notes. Config location: consult Windsurf MCP documentation.

---

Note on prompt support: MCP prompts require explicit client-side UI (a slash command picker or equivalent). Not all clients have implemented this yet. When prompts aren't available, ask ad-hoc — the tools work the same way and the model applies the same workflow.

Architecture

MCP Client (e.g. Claude Desktop)
  |
  | (spawns per-session)
  v
docker run --rm -i dns-mcp python server.py
  |
  | stdin/stdout (MCP stdio transport)
  v
FastMCP server (server.py)
  |  - All 29 tools
  |  - dnspython for DNS queries
  |  - requests for RDAP only

No network ports. No auth tokens. No proxy. The MCP client manages the container lifecycle — one container per session, cleaned up on exit.

Day-to-Day

Testing

Unit tests — tool logic, input validation, error handling:

make test    # runs pytest inside container

End-to-end stdio — full MCP protocol over stdin/stdout:

./test-mcp-stdio.sh

Security

• No shell execution — all DNS via dnspython, RDAP via requests
• Strict domain validation (regex allowlist)
• IP address validation (ipaddress module)
• Query type allowlist
• Non-root container user (claude, uid 1000)
• SPF recursion limit enforced (RFC 7208)
• RDAP: input validated before HTTP request, 10s timeout, max 3 redirects

File Structure

dns-mcp/
├── server.py              # FastMCP server (29 tools, 4 prompts, stdio transport)
├── Dockerfile             # Single-stage Alpine image
├── docker-compose.yml     # Build target
├── Makefile               # build/test/shell
├── requirements.txt       # Python dependencies
├── test-mcp-stdio.sh      # End-to-end stdio test
├── prompts/               # Analyst prompt text files (MCP prompts)
├── tools/                 # CLI shell tool wrappers
└── tests/
    └── test_tools.py      # pytest unit tests

Contributing

pip install pre-commit
pre-commit install

That's it. On every commit, ruff will lint and auto-fix staged Python files. The full test suite (pytest + stdio e2e) runs in CI on every push and pull request.

Remote / HTTP Transport

The remote branch contains the HTTP Streamable transport version of this server, including a Flask auth proxy sidecar, bearer token authentication, fail2ban integration, and instructions for exposing the server via an HTTPS reverse proxy. See that branch if you need network-accessible deployment.

License

MIT