adguard-mcp

WIP

MCP server for AdGuard Home - manage DNS filtering.

GitHub repo → npm: @solomonneas/adguard-mcp →
33
tools exposed
3
write-gate tiers
multi
instances + Sync

WHAT IT DOES

AdGuard MCP exposes AdGuard Home to your AI client across one or more instances, plus AdGuardHome Sync status and control. Reads are open: server status, stats, the DNS query log, filter lists, clients, and a check_host lookup that shows exactly what AdGuard would do with a hostname. Filtering and client changes sit behind a three-tier write-gate, so the model cannot disable protection or wipe the rules block from a hallucinated call. It is for homelab operators running one or several AdGuard Home boxes who want to inspect and tune DNS filtering from an assistant.

Status: work in progress. Published to npm as @solomonneas/adguard-mcp; expect the surface to keep shifting while it stabilizes.

INSTALL

$ npm install -g @solomonneas/adguard-mcp
 
# or run without installing
$ npx -y @solomonneas/adguard-mcp

Set per-instance env vars; at least one instance is required. The instance name comes from the middle segment of the var, so adding ADGUARD_LIVINGROOM_* registers a second box automatically. AdGuardHome Sync uses its own prefix.

# primary instance (required)
ADGUARD_PRIMARY_URL=http://192.0.2.10
ADGUARD_PRIMARY_USERNAME=admin
ADGUARD_PRIMARY_PASSWORD=<password>
 
# optional second instance
ADGUARD_SECONDARY_URL=http://192.0.2.11
ADGUARD_DEFAULT_INSTANCE=primary
 
# optional AdGuardHome Sync
ADGUARDHOME_SYNC_URL=http://192.0.2.10:8080

TOOLS EXPOSED

33 tools across three gating tiers. Reads need no flag; safe writes require confirm: true; destructive ops also require destructive: true. Every tool accepts an optional instance arg to address a non-default box.

Reads (14) · open

adguard_status
adguard_stats
adguard_query_log
adguard_list_filter_lists
adguard_list_user_rules
adguard_list_clients
adguard_list_blocked_services_catalog
adguard_check_host
adguard_get_blocked_services
adguard_get_dns_config
adguard_get_safesearch_settings
adguard_sync_status
adguard_sync_health
adguard_sync_logs

Safe writes (13) · confirm: true

adguard_add_user_rule
adguard_remove_user_rule
adguard_add_filter_list
adguard_remove_filter_list
adguard_toggle_filter_list
adguard_set_client_blocked_services
adguard_refresh_filter_lists
adguard_add_client
adguard_update_client
adguard_set_blocked_services
adguard_toggle_safesearch
adguard_toggle_safebrowsing
adguard_sync_run

Destructive (6) · confirm + destructive

adguard_replace_user_rules
adguard_toggle_protection
adguard_delete_client
adguard_clear_query_log
adguard_reset_stats
adguard_sync_clear_logs

CLIENT CONFIG

Sample mcpServers entry (Claude Desktop / Claude Code / any MCP client). The same shape works in OpenClaw, Codex CLI, and Hermes; see the README for those formats.

{
  "mcpServers": {
    "adguard": {
      "command": "npx",
      "args": ["-y", "@solomonneas/adguard-mcp"],
      "env": {
        "ADGUARD_PRIMARY_URL": "http://192.0.2.10",
        "ADGUARD_PRIMARY_USERNAME": "admin",
        "ADGUARD_PRIMARY_PASSWORD": "your-password"
      }
    }
  }
}

Credentials only live in memory after env-load and are redacted from logs and error messages. If no Sync URL is set, the Sync tools stay listed but return a clear config error when called.