agentic-dns

Local agentic DNS stack combining Pi-hole, CoreDNS, dnsdist, and Unbound with an MCP-compatible stdio server for programmatic control.

---

Machine-friendly summary

Name: agentic-dns
URL: https://github.com/dedsecorg/agentic-dns
ShortDescription: Local agentic DNS stack combining Pi-hole, CoreDNS, dnsdist, and Unbound with an MCP-compatible stdio server for programmatic control.
Keywords: agentic-dns, mcp, dns, pi-hole, coredns, dnsdist, unbound, selfhosted, dns-middleware
EntryPoint: bin/agentic-dns
Install:
  - git clone https://github.com/dedsecorg/agentic-dns.git
  - ./install.sh
CLIExamples:
  - MCP: agentic-dns mcp
  - API: agentic-dns api
MCP:
  - protocol: stdio
  - capabilities: dns_status,dns_query,dns_trace,dns_health,dns_routes,dns_pihole_log,dns_bypass
  - control-endpoint: stdio
  - example-config-snippet: |
      mcp:
        name: agentic-dns
        protocol: stdio
        command: ["agentic-dns","mcp"]
Maintainer:
  - name: dedsecorg
  - contact: https://github.com/dedsecorg
License: MIT
ReleaseTag: v1.5.0
Notes: Exposes MCP features for query/response and local firewall integration. See README.md for full architecture and network requirements.

---

Quick Installation Options

Option 1: 1-Line Script (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/dedsecorg/agentic-dns/main/install.sh | bash

Option 2: Docker Container (GHCR)

docker run -d --net=host ghcr.io/dedsecorg/agentic-dns:latest

Option 3: Node.js / npx Package

npx agentic-dns status

---

60-Second AI Agent Onboarding

agentic-dns provides out-of-the-box MCP JSON-RPC protocol support for AI agents.

1. Claude Code

claude mcp add agentic-dns agentic-dns mcp

2. Cursor / Windsurf / Copilot

Add to your project or user .mcp.json file:

{
  "mcpServers": {
    "agentic-dns": {
      "command": "agentic-dns",
      "args": [
        "mcp"
      ],
      "env": {
        "PIHOLE_HOST": "127.0.0.1",
        "AGENTIC_DNS_API_PORT": "8099"
      }
    }
  }
}

3. Hermes Agent

Run hermes mcp add agentic-dns agentic-dns mcp.

---

Example AI Assistant Prompts

Once connected, ask your AI coding assistant:

• "Check if any local DNS resolvers in the chain are down or unhealthy."
• "Trace the packet path for github.com across loopback and outbound interfaces."
• "Bypass stubby and route DNS traffic through unbound."
• "Show recent Pi-hole query statistics from SQLite."

---

Key Features

• Zero External Dependencies: Core POSIX Bash execution + standard Unix tools (dig, ss, tcpdump, nft, sqlite3, socat, jq). Zero idle RAM usage.
• Native Model Context Protocol (MCP): Exposes dns_status, dns_query, dns_trace, dns_health, dns_routes, dns_pihole_log, and dns_bypass to AI agents.
• Live Inter-Service Tracing (trace): Runs background tcpdump captures across loopback and network interfaces to visualize packet hop progression and latency bottlenecks.
• Automated Failover (bypass): Dynamically rewrites dnsdist configuration and reloads routing daemons to bypass failing resolvers in milliseconds.
• Encrypted DNS Interception (enforce): Applies non-destructive nftables rules to redirect Private DNS (DoT port 853) and drop Google DoQ (UDP/443).
• High-Performance Rust Server (agentic-dns-server): Includes server/ crate for DoT/DoH proxy handling and REST telemetry.

---

MCP configuration

mcp:
  name: agentic-dns
  protocol: stdio
  command: ["agentic-dns","mcp"]
  capabilities:
    - dns_status
    - dns_query
    - dns_trace
    - dns_health
    - dns_routes
    - dns_pihole_log
    - dns_bypass
  version: 1.0

---

6-Tier Architecture Pipeline

  [Client / Mobile Device]
            |
            v
      pihole (:53)          <- Ad blocking & FTL SQLite telemetry
            |
            v
     coredns (:5352)        <- Split-horizon mesh zone routing (Tailscale / Nebula)
            |
            v
     dnsdist (:5330)        <- Dynamic load balancing & bypass failover policy
            |
   +--------+--------+
   |                 |
   v                 v
 unbound (:5335)   dnscrypt-proxy (:5354) / stubby (:5360)
   |                 |
   v                 v
 [VPN / Upstream]  [DoH / DoT Cloud Upstreams]

---

CLI Command Quick Reference

# Start stdio MCP JSON-RPC Server
agentic-dns mcp

# Start REST API server on port 8099
agentic-dns api

# View active DNS chain status and listening ports
agentic-dns status

# Execute live inter-service packet trace
agentic-dns trace google.com

# Failover failing service to backup
agentic-dns bypass stubby unbound

# Check health of all DNS listeners
agentic-dns health

# View Pi-hole query logs
agentic-dns pihole-log

# Start the Rust API/DoT proxy server (if built)
agentic-dns server

---

Tags / Keywords

agentic-dns, mcp, dns, pi-hole, coredns, dnsdist, unbound, selfhosted

---

License

MIT License - Free and Open Source.