<!-- content-guard: allow private-ipv4 file -->

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