@solomonneas/adguard-mcp weekly downloads statistics

adguardctrl

An operator control CLI for AdGuard Home, with an MCP adapter for assistant workflows and back-compatible launchers.

Website · Quickstart

adguardctrl is an operator control CLI for AdGuard Home, the self-hosted DNS sinkhole. It gives shell, cron, CI, and assistant workflows one typed control surface for inspecting network-wide DNS filtering across one or more boxes. The npm package remains @solomonneas/adguard-mcp for compatibility and still ships the back-compatible adguard-mcp bin; new MCP launchers can start the adapter with adguardctrl mcp.

What it does

adguardctrl speaks the AdGuard Home API across one or more instances, plus optional AdGuardHome Sync status and control. The direct CLI is read-only today, covering server status, stats, the DNS query log, filter lists, named clients, DNS rewrites, DNS and TLS config, DHCP status, and a check-host lookup that shows exactly what AdGuard would do with a hostname.

For assistant clients, adguardctrl mcp starts the stdio MCP adapter used by Claude Desktop, Claude Code, Codex CLI, OpenClaw, Hermes, and other Model Context Protocol clients. That adapter keeps the original adguard-mcp tool surface and safety model: reads are open, writes require an explicit confirm: true, and destructive operations additionally require destructive: true, so an agent cannot disable filtering or wipe rules on a hallucinated call.

Quickstart

Install globally:

Or run via npx with no install:

Then use adguardctrl from your shell, or wire the package into an MCP client. The minimal config for any client that speaks the standard mcpServers shape (Claude Desktop, Claude Code):

Once connected, ask your client to call adguard_status to confirm it can reach the box. Reads work immediately; writes need the confirm: true flag and destructive ops also need 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 |…