adguardctrl

adguardctrl

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

Website

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:

npm install -g @solomonneas/adguard-mcp

Or run via npx with no install:

npx -y @solomonneas/adguard-mcp

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

{
  "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"
      }
    }
  }
}

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.

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.

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.

Configuration

Set per-instance env vars. At least one instance is 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_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.

CLI

adguardctrl is the package's primary operator entry point for shells, cron, and CI. It shares the AdGuardClient / AdGuardSyncClient core with the MCP adapter and reads the same env config. It exposes only the Tier-1 read tools; writes stay in the MCP/plugin surface behind the tier gates.

npx @solomonneas/adguard-mcp@latest status
# or, installed globally:
adguardctrl status
adguardctrl stats
adguardctrl querylog --limit 20 --blocked-only
adguardctrl check-host youtube.com --client kid-tablet
adguardctrl clients list
adguardctrl filters list
adguardctrl rewrites list
adguardctrl dns-config
adguardctrl tls status              # private key is redacted
adguardctrl sync health             # exit 1 if Sync is not healthy (cron-friendly)
adguardctrl status --json           # raw JSON for piping
adguardctrl status --instance secondary

Run adguardctrl help for the full command and flag list. --instance <name> targets a non-default AdGuard Home box; --json emits raw JSON instead of the concise human-readable summary. Exit codes: 0 success, 1 runtime error (backend unreachable / call failed, and sync health when not healthy), 2 usage error (unknown command/flag or bad value).

Starting the MCP server

adguardctrl mcp (or the back-compat adguard-mcp bin) starts the stdio MCP adapter. If a launcher referenced the file path dist/mcp-server.js directly, it keeps working; new launchers can point at dist/mcp-bin.js (or dist/cli.js mcp). Launchers that use the adguard-mcp bin name need no change.

Setup per client

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows): use the mcpServers block from Quickstart.

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

Why not just give the agent the AdGuard Home API?

• The raw AdGuard Home API has no agent-safety layer. Every endpoint is one call away, including the ones that disable all blocking or wipe your rules. The MCP adapter keeps reads open and gates writes behind confirm: true and destructive ops behind destructive: true, so a hallucinated tool call cannot silently break your network.
• curl or a generic HTTP MCP server would mean the model hand-builds request bodies, handles Basic auth, and remembers which AdGuard quirk applies (the nested {name, data} client body, milliseconds-from-midnight schedules, the PUT vs POST split). adguardctrl and its MCP adapter encode those as typed commands and tools, so the caller picks an intent, not an HTTP shape.
• A single-instance integration does not match a real homelab. adguardctrl resolves any number of instances from env vars by name and lets commands or MCP tools target a non-default box with one instance arg, plus optional AdGuardHome Sync control alongside.
• Clicking the web dashboard works, but not from inside an assistant and not across several boxes at once. This is the same control surface, available to the agent you already have open.

What adguardctrl is not

adguardctrl is not a hosted service, a replacement for the AdGuard Home dashboard, or an autonomous network manager.

It does not:

• run a daemon, scheduler, or background process
• store or proxy your DNS traffic
• make any write without an explicit confirm: true flag from the caller
• perform a destructive operation without confirm: true and destructive: true together
• talk to AdGuard's hosted DNS product; it targets self-hosted AdGuard Home instances you run

License

MIT. See LICENSE.