NextDNS-Agent-MCP

Ask your AI app about your DNS in plain words. It looks at your stats and logs, and changes your blocklists, parental control and settings for you. Every change can be undone, and deleting things always asks you twice.

You: What got blocked on my phone today, and why?
AI:  Reads your NextDNS log: 214 blocked, mostly trackers from OISD, and one site
     from your denylist. Shows a chart.

You: My son's game doesn't load. Find out why and fix it.
AI:  Watches the live log while he opens it, sees roblox.com blocked by the
     "gaming" category, and asks if it should allow it on weekends only.

You: Block TikTok on the Kids profile, except Friday 6 to 9 pm.
AI:  Blocks TikTok and sets recreation time. Says how to undo it.

How it works

The server is a small program you run yourself. Your AI app talks to it through MCP (Model Context Protocol), the standard way AI apps use outside tools. The server talks to NextDNS through its official API, with your API key. Nobody else is in between: no account, no cloud service of ours, no tracking.

flowchart LR
    A["Your AI app<br/>(Claude, ChatGPT, Codex,<br/>Cursor, Gemini, ...)"] -->|MCP| S["NextDNS-Agent-MCP<br/>(on your computer or server)"]
    S -->|"API key"| N["NextDNS"]

More in docs/how-it-works.md.

Related MCP server: next-dns-mcp

Words you'll see

Choose how to run it

What it can do

Look. Your profiles and every setting in plain words. Analytics: allowed and blocked, top domains, block reasons, devices, IPs, protocols, query types, DNSSEC, encryption, countries and big tech companies, for any time span and also over time. Charts as pictures. The query log, searched and filtered, or downloaded.

Find out why. check_domain makes a real DNS query through the profile and tells you if a domain is blocked, and by what: the denylist, a blocklist, a category. watch_logs watches queries live while you open an app.

Change. The denylist and allowlist (many at once), privacy blocklists and native tracker protection, every security protection and blocked TLDs, parental control (services, categories, safe search, YouTube restricted mode, recreation time), DNS rewrites, logs, block page and performance settings. Everything the NextDNS API allows.

Profiles. Create a profile (with NextDNS's usual protections, empty, or as a copy of another), compare two profiles, rename them.

Undo. Every change is saved with how things were before. Ask "undo that", or press Undo on the settings page.

Backups. Save a full copy of a profile, download it as a file, and put it back later, or make a new profile from it.

Ask twice. Deleting a profile, clearing logs and overwriting a profile from a backup need a double confirmation: the AI must ask you and get a yes first.

Updates, if you want them. Get told when there's a new release, or let it update itself, official releases only. See docs/updates.md.

A settings page. On the web version, open /settings to paste your API key, choose what the AI may do with each profile, see and disconnect AI apps, undo changes, and manage backups.

All 23 tools: docs/tools.md. Ideas for what to ask: docs/examples.md.

Safety and privacy

• Your choice, per profile: full, read only or hidden. Hidden profiles are never shown to the AI.

• Your choice, per app: each AI app connected over the internet gets only the profiles you tick, with or without changes.

• Undo for every change, and a double confirmation for anything that deletes or overwrites.

• A brake: at most 30 changes a minute, and a read-only switch for everything.

• Your key stays yours: it goes only to NextDNS, and is stored encrypted when you paste it on the settings page.

More in docs/safety.md and docs/privacy.md.

Quick start (about 5 minutes)

1. Install uv, a small free tool that installs Python programs.

2. Install the server:

   uv tool install git+https://github.com/s17sh70x2jfl031ag/NextDNS-Agent-MCP

3. Get your API key: sign in at my.nextdns.io/account, scroll to the bottom (API), show the key and copy it.

4. Save it in the settings file:

   mkdir -p ~/.config/nextdns-agent-mcp

   echo "NEXTDNS_API_KEY=paste-your-key-here" > ~/.config/nextdns-agent-mcp/.env

5. Check it. It lists your profiles and changes nothing:

   nextdns-agent-mcp check

6. Connect your AI app. For example Claude Code:

   claude mcp add -s user nextdns -- nextdns-agent-mcp stdio

   For Claude Desktop, ChatGPT, Codex, Cursor, VS Code, Gemini CLI, OpenClaw, Hermes Agent, Goose, Cline, Roo Code, Continue, Windsurf, Zed, LM Studio, OpenCode, Kiro, GitHub Copilot CLI, Amp, Warp, JetBrains AI Assistant, Qwen Code, Crush, Augment Code and any other MCP app, see docs/connect-your-ai.md.

7. Ask your AI: "Use the NextDNS tools: what got blocked today?"

All the guides

Help and feedback

Issues are public, so leave out your API key, profile IDs and anything from your logs.

Credits

NextDNS-Agent-MCP was made by s17sh70x2jfl031ag. NextDNS is a trademark of its owners; this project isn't made by or affiliated with them.

GitHub's "Cite this repository" button uses CITATION.cff.

License

Apache License 2.0, with the notices in NOTICE. Copyright 2026 s17sh70x2jfl031ag and NextDNS-Agent-MCP contributors.