adguard-home-mcp 0.2.0

MCP server for AdGuard Home — wraps the local REST API. Supports stdio and streamable HTTP.

AdGuard-Home-MCP

MCP server wrapping the AdGuard Home local REST API.

Exposes a curated, parameter-driven tool surface (status, stats, DNS config, blocklist/allowlist management, custom rules, query log, per-client policies, protection toggle) over either stdio (for direct MCP clients like Claude Desktop) or streamable HTTP (for MCP aggregators / gateways).

Tools

Tool	Purpose
get_status	Service status (version, protection, DNS port)
get_stats	24h query stats, top domains, top clients
get_dns_config	View upstreams / bootstrap / cache config
set_upstreams	Replace upstream DNS (and optionally bootstrap)
list_filter_lists	All blocklists + allowlists with state and rule counts
add_filter_list	Add a blocklist or allowlist (kind="block" | "allow")
remove_filter_list	Remove a blocklist or allowlist by URL
toggle_filter_list	Enable/disable a list without removing it
refresh_filter_lists	Force-refresh lists from source URLs
get_custom_rules	Read user filter rules
update_custom_rules	Append (default) or replace user rules
check_host	"Would AGH block this hostname?" preview
query_log / clear_query_log	Browse / wipe DNS query history
list_clients / update_client	Per-device policies
set_protection	Pause/resume filtering globally (with optional auto-resume)

17 tools. Block/allow distinction and append/replace semantics are parameters rather than separate tools.

Environment

Var	Required	Notes
ADGUARD_HOME_URL	yes	Base URL of the AGH admin interface, e.g. http://adguard.lan
ADGUARD_HOME_USERNAME	yes	Admin user from the AGH setup wizard
ADGUARD_HOME_PASSWORD	yes	Admin password
ADGUARD_HOME_VERIFY_SSL	no	Default true; set false for self-signed certs
MCP_TRANSPORT	no	stdio (default), or streamable_http for service mode
MCP_HTTP_HOST	no	Default 0.0.0.0 (only used with streamable_http)
MCP_HTTP_PORT	no	Default 3000 (only used with streamable_http)

Run

stdio

ADGUARD_HOME_URL=http://adguard.lan \
ADGUARD_HOME_USERNAME=admin \
ADGUARD_HOME_PASSWORD=REPLACE_ME \
  uvx adguard-home-mcp

Streamable HTTP (Docker)

docker build -t adguard-home-mcp .
docker run --rm -p 3000:3000 \
  -e ADGUARD_HOME_URL=http://adguard.lan \
  -e ADGUARD_HOME_USERNAME=admin \
  -e ADGUARD_HOME_PASSWORD=REPLACE_ME \
  adguard-home-mcp

The container defaults to MCP_TRANSPORT=streamable_http on port 3000. The MCP endpoint is at /mcp.

Client config

Claude Desktop / Claude Code (stdio)

{
  "mcpServers": {
    "adguard-home": {
      "command": "uvx",
      "args": ["adguard-home-mcp"],
      "env": {
        "ADGUARD_HOME_URL": "http://adguard.lan",
        "ADGUARD_HOME_USERNAME": "admin",
        "ADGUARD_HOME_PASSWORD": "REPLACE_ME"
      }
    }
  }
}

Streamable HTTP client

{
  "mcpServers": {
    "adguard-home": {
      "type": "http",
      "url": "http://adguard-host:3000/mcp"
    }
  }
}

Reference

• AGH OpenAPI spec: https://github.com/AdguardTeam/AdGuardHome/blob/master/openapi/openapi.yaml
• All endpoints under /control/, HTTP Basic auth.

License

MIT.