mcp-dns

Model Context Protocol server for DNS lookups — gives AI agents two tools: resolve_dns (A, AAAA, CNAME, MX, TXT, NS, SOA, SRV, CAA) and reverse_dns (PTR). Built on node:dns only: no external APIs, no keys, no telemetry.

Playground

No install needed — try live DNS lookups in the browser at https://yeeeeezus.github.io/mcp-dns/ (DNS-over-HTTPS queries go straight from your browser to Google Public DNS). The server below is the same idea for AI agents.

Why

Agents doing web work, security review, infrastructure debugging or mail deliverability checks constantly need DNS facts: where does this domain point, what are its nameservers, does it have SPF/DMARC records, what does this IP reverse to. Instead of hoping the model remembers a shell one-liner, give it typed tools that return structured answers over the MCP stdio transport.

Tools

resolve_dns

parameter	type	description
domain	string	domain to resolve, e.g. example.com
recordType	enum	A (default), AAAA, CNAME, MX, TXT, NS, SOA, SRV, CAA

For SRV, pass the full query name (e.g. _xmpp-server._tcp.gmail.com).

reverse_dns

parameter	type	description
ip	string	IPv4 or IPv6 address, e.g. 1.1.1.1

Example exchange

Request:

{ "name": "resolve_dns", "arguments": { "domain": "gmail.com", "recordType": "MX" } }

Response:

[
  { "exchange": "gmail-smtp-in.l.google.com", "priority": 5, "type": "MX" },
  { "exchange": "alt1.gmail-smtp-in.l.google.com", "priority": 10, "type": "MX" },
  { "exchange": "alt2.gmail-smtp-in.l.google.com", "priority": 20, "type": "MX" },
  { "exchange": "alt3.gmail-smtp-in.l.google.com", "priority": 30, "type": "MX" },
  { "exchange": "alt4.gmail-smtp-in.l.google.com", "priority": 40, "type": "MX" }
]

Install

Run directly without cloning:

$ npx github:yeeeeezus/mcp-dns

or from a checkout:

$ git clone https://github.com/yeeeeezus/mcp-dns
$ cd mcp-dns && npm install && npm run build
$ node dist/index.js

Claude Desktop / any MCP client

{
  "mcpServers": {
    "mcp-dns": {
      "command": "npx",
      "args": ["github:yeeeeezus/mcp-dns"]
    }
  }
}

Behavior notes

• ENOTFOUND / ENODATA are mapped to clean tool errors ("no MX records found for …") instead of stack traces.
• Hostnames are validated before resolution; URLs and paths are rejected up front.
• TXT record chunks are joined into single strings (the DNS wire format splits long TXT values).
• Output is pretty-printed JSON text, one record set per call.

Development

$ npm install
$ npm test

8 tests, including a full integration test that spawns the built server and speaks MCP JSON-RPC over stdio: initialize handshake, tools/list, two real tools/call resolutions, and an error-path check.

License

MIT