mcp-dns-insights

Capture the DNS queries leaving your Mac and serve them to Claude over the Model Context Protocol so Claude can analyse your traffic patterns and hand back a structured JSON overview.

It answers questions like:

• Which domains does my machine talk to the most?
• How much of my traffic is advertising, analytics, or telemetry?
• When am I busiest, and were there any unusual bursts of activity?

How it works

 ┌────────────┐     ┌──────────────┐     ┌───────────────┐     ┌────────┐
 │  tcpdump   │ --> │   capture    │ --> │   SQLite db   │ <-- │  MCP   │ <── Claude
 │ (port 53)  │     │   daemon     │     │  (dns.db)     │     │ server │
 └────────────┘     └──────────────┘     └───────────────┘     └────────┘

1. A capture daemon runs tcpdump, parses each DNS question off the wire, and appends it to a local SQLite database.
2. An MCP server exposes read-only tools over stdio. Claude calls analyze_patterns (and friends) and receives JSON it can summarise.

The two halves are decoupled through the database: capture is a single writer, the server is a read-only consumer.

Install

Requires Python 3.10+ and the tcpdump that ships with macOS.

git clone https://github.com/luke-nielsen/mcp-dns-insights.git
cd mcp-dns-insights
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Usage

1. Capture DNS traffic

Packet capture needs root, so run the daemon under sudo:

sudo -E mcp-dns-insights capture

Leave it running in the background (or install it as a launchd job — see below). Use -i en0 to pin a specific interface; the default any captures all of them.

2. Inspect from the terminal

mcp-dns-insights stats --hours 24      # human-readable summary
mcp-dns-insights stats --hours 24 --json
mcp-dns-insights info                  # database location & span

3. Connect it to Claude

The server speaks MCP over stdio. Register it with Claude Code:

claude mcp add dns-insights -- mcp-dns-insights serve

or add it to your MCP host config manually:

{
  "mcpServers": {
    "dns-insights": {
      "command": "mcp-dns-insights",
      "args": ["serve"]
    }
  }
}

Then ask Claude: "Analyse my DNS traffic from the last 24 hours and tell me what's noteworthy."

MCP tools

Tool	Purpose
analyze_patterns	Full JSON overview: top domains, categories, temporal, notes.
recent_queries	The most recent queries as a JSON list.
search_domain	Find queries whose hostname matches a substring.
database_info	Database path, size, and time span.

Shape of analyze_patterns

{
  "summary": { "total_queries": 4213, "unique_hostnames": 612, "unique_domains": 241, "window": { ... } },
  "top_hostnames": [ { "name": "api.github.com", "count": 88 }, ... ],
  "top_domains":   [ { "name": "github.com", "count": 140 }, ... ],
  "query_types":   { "A": 3100, "AAAA": 980, "HTTPS": 133 },
  "clients":       [ { "name": "192.168.1.10", "count": 4100 } ],
  "resolvers":     [ { "name": "1.1.1.1", "count": 4213 } ],
  "categories":    { "analytics": 210, "advertising": 95, "cdn": 540 },
  "flagged_domains": [ { "domain": "doubleclick.net", "category": "advertising", "count": 60 } ],
  "temporal":      { "by_hour": { ... }, "busiest_hour": { ... }, "peak_queries_per_minute": 47 },
  "observations":  [ "github.com accounts for 140 queries (3% of the total).", ... ]
}

Run as a launchd job (optional)

Create ~/Library/LaunchAgents/us.radiusgroup.mcp-dns-insights.plist (capture needs root, so a LaunchDaemon in /Library/LaunchDaemons is the better fit):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>us.radiusgroup.mcp-dns-insights</string>
  <key>ProgramArguments</key>
  <array>
    <string>/path/to/.venv/bin/mcp-dns-insights</string>
    <string>capture</string>
  </array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
</dict>
</plist>

sudo cp us.radiusgroup.mcp-dns-insights.plist /Library/LaunchDaemons/
sudo launchctl load /Library/LaunchDaemons/us.radiusgroup.mcp-dns-insights.plist

Configuration

All settings have sensible defaults and can be overridden via the environment:

Variable	Default
MCP_DNS_INSIGHTS_DB	~/Library/Application Support/mcp-dns-insights/dns.db
MCP_DNS_INSIGHTS_HOME	data directory (overrides the default location)
MCP_DNS_INSIGHTS_IFACE	any
MCP_DNS_INSIGHTS_FILTER	udp port 53 or tcp port 53
MCP_DNS_INSIGHTS_TCPDUMP	tcpdump
MCP_DNS_INSIGHTS_FLUSH_INTERVAL	2.0 (seconds)
MCP_DNS_INSIGHTS_FLUSH_BATCH	100 (queries)

Privacy

The database contains a record of every hostname your Mac looked up — that is sensitive. It is stored only on your machine and is never transmitted anywhere except to the local MCP server you explicitly connect to Claude. The .gitignore excludes *.db so capture data is never committed.

Note: queries answered by DNS-over-HTTPS/TLS (e.g. some browsers' built-in secure DNS) are encrypted and will not be visible to a port-53 capture.

Development

pip install -e ".[dev]"
pytest          # run the test suite
ruff check .    # lint

License

MIT — see LICENSE.