adguard-mcp

MCP server exposing AdGuard Home read/write tools across one or more instances. 28 tools (11 reads / 12 safe-writes / 5 destructive). Three-tier write gating: reads are open, writes require confirm: true, destructive ops require confirm: true + destructive: true.

Tools

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

| 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). |

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

| 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). |

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

| 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). |

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.

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