adguard-mcp

MCP server exposing AdGuard Home read/write tools across one or more instances, plus AdGuardHome Sync status and control. 33 tools (14 reads / 13 safe-writes / 6 destructive). Three-tier write gating: reads are open, writes require confirm: true, destructive ops require confirm: true + destructive: true.

Tools

Reads (14): 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.

| Tool | Description | |---|---| | adguard_status | Server status + protection state (GET /control/status). | | adguard_stats | Stats window: top queries, blocked counts, clients (GET /control/stats). | | adguard_query_log | DNS query log slice with filters (GET /control/querylog). | | adguard_list_filter_lists | Subscribed blocklists + allowlists (GET /control/filtering/status). | | adguard_list_user_rules | Custom user rules (GET /control/filtering/status). | | adguard_list_clients | Configured named clients (GET /control/clients). | | adguard_list_blocked_services_catalog | Available service IDs to block (GET /control/blocked_services/services). | | adguard_check_host | Test what AGH would do with a hostname: filter decision, matched rules, CNAME chain, IPs (GET /control/filtering/check_host). | | adguard_get_blocked_services | Global blocked-services list + weekly schedule (GET /control/blocked_services/get). | | adguard_get_dns_config | DNS upstreams, bootstrap, cache, parallel resolution, blocking mode (GET /control/dns_info). | | adguard_get_safesearch_settings | SafeSearch enabled state + per-engine flags (GET /control/safesearch/status). | | adguard_sync_status | AdGuardHome Sync origin/replica status (GET /api/v1/status). | | adguard_sync_health | AdGuardHome Sync health check (HEAD /healthz). | | adguard_sync_logs | AdGuardHome Sync in-memory logs (GET /api/v1/logs). |

Safe writes (13, require 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.

| Tool | Description | |---|---| | adguard_add_user_rule | Append a single user filter rule (POST /control/filtering/set_rules). | | adguard_remove_user_rule | Remove a single user filter rule by exact match (POST /control/filtering/set_rules). | | adguard_add_filter_list | Subscribe to a new blocklist or allowlist URL (POST /control/filtering/add_url). | | adguard_remove_filter_list | Unsubscribe from a filter list by URL (POST /control/filtering/remove_url). | | adguard_toggle_filter_list | Enable or disable a subscribed filter list (POST /control/filtering/set_url). | | adguard_set_client_blocked_services | Set per-client blocked services + schedule (POST /control/clients/update). | | adguard_refresh_filter_lists | Force refresh subscribed filter lists immediately (POST /control/filtering/refresh). | | adguard_add_client | Register a new named client with per-client settings (POST /control/clients/add). | | adguard_update_client | Full update for an existing named client; body is nested {name, data} (POST /control/clients/update). | | adguard_set_blocked_services | Set GLOBAL blocked services + optional weekly schedule; accepts HH:MM strings or ms (PUT /control/blocked_services/update). | | adguard_toggle_safesearch | Enable or disable SafeSearch globally with per-engine flags (PUT /control/safesearch/settings). | | adguard_toggle_safebrowsing | Enable or disable AGH SafeBrowsing (POST /control/safebrowsing/enable or /disable). | | adguard_sync_run | Trigger AdGuardHome Sync immediately (POST /api/v1/sync). |

Destructive (6, require confirm: true + destructive: true): adguard_replace_user_rules, adguard_toggle_protection, adguard_delete_client, adguard_clear_query_log, adguard_reset_stats, adguard_sync_clear_logs.

| Tool | Description | |---|---| | adguard_replace_user_rules | Wholesale replace the user rules block (POST /control/filtering/set_rules). | | adguard_toggle_protection | Enable or disable global filtering; off stops ALL blocking (POST /control/protection). | | adguard_delete_client | Remove a configured named client; per-client rules and stats are lost (POST /control/clients/delete). | | adguard_clear_query_log | Wipe the DNS query log (POST /control/querylog_clear). | | adguard_reset_stats | Zero the stats window (POST /control/stats_reset). | | adguard_sync_clear_logs | Clear AdGuardHome Sync in-memory logs (POST /api/v1/clear-logs). |

Configuration

Set per-instance env vars. At least one instance is required.

ADGUARD_PRIMARY_URL=http://192.168.1.10
ADGUARD_PRIMARY_USERNAME=admin
ADGUARD_PRIMARY_PASSWORD=<password>

# Optional second instance:
ADGUARD_SECONDARY_URL=http://192.168.1.11
ADGUARD_SECONDARY_USERNAME=admin
ADGUARD_SECONDARY_PASSWORD=<password>

# Optional: which instance is default when a tool omits the `instance` arg:
ADGUARD_DEFAULT_INSTANCE=primary

Instance names are derived from the env-var middle segment (case-insensitive). Add ADGUARD_LIVINGROOM_URL/USERNAME/PASSWORD and the MCP picks it up on next start.

Every tool accepts optional instance: "<name>" to address a non-default box.

AdGuardHome Sync is optional and uses a separate env prefix so it does not collide with AdGuard Home instance names:

ADGUARDHOME_SYNC_URL=http://192.0.2.10:8080

# Optional, only when the Sync API is configured with Basic auth:
ADGUARDHOME_SYNC_USERNAME=sync
ADGUARDHOME_SYNC_PASSWORD=<password>

ADGUARD_SYNC_URL/USERNAME/PASSWORD is also accepted as an alias and is reserved for the Sync server, not an AdGuard Home instance named sync.

If neither Sync URL env var is set, Sync tools remain listed but return a clear config error when called.

Install

npm install -g @solomonneas/adguard-mcp

Or run via npx:

npx -y @solomonneas/adguard-mcp

Setup

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Claude Code

claude mcp add adguard -s user -- npx -y @solomonneas/adguard-mcp

Then export env vars in your shell (~/.bashrc, ~/.zshrc) or pass --env flags.

OpenClaw

Plugin loads automatically once installed. Config goes in your ~/.openclaw/openclaw.json plugins.entries.adguard (or use the bundled openclaw.plugin.json):

{
  "plugins": {
    "entries": {
      "adguard": {
        "package": "@solomonneas/adguard-mcp",
        "activation": { "onStartup": true }
      }
    }
  }
}

Env vars from ~/.openclaw/workspace/.env are inherited by the plugin.

Hermes Agent

Add to ~/.config/hermes/agents.yaml:

mcp_servers:
  adguard:
    command: npx
    args: ["-y", "@solomonneas/adguard-mcp"]
    env:
      ADGUARD_PRIMARY_URL: http://192.168.1.10
      ADGUARD_PRIMARY_USERNAME: admin
      ADGUARD_PRIMARY_PASSWORD: your-password

Codex CLI

~/.codex/config.toml:

[mcp_servers.adguard]
command = "npx"
args = ["-y", "@solomonneas/adguard-mcp"]

[mcp_servers.adguard.env]
ADGUARD_PRIMARY_URL = "http://192.168.1.10"
ADGUARD_PRIMARY_USERNAME = "admin"
ADGUARD_PRIMARY_PASSWORD = "your-password"

Safety

Credentials only live in memory after env-load and are redacted from logs and error messages.
Tier 2 writes require an explicit confirm: true arg; the JSON schema documents this on every write tool.
Tier 3 destructive ops additionally require destructive: true. The model cannot disable protection or overwrite the rules block from a hallucinated tool call.

License

MIT

adguard

Summary

Install to Claude Code