convez.ai
MCP Server
solomonneas

adguard-mcp

solomonneas/adguard-mcp

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server for AdGuard Home: 15 tools across read/safe-write/destructive tiers, multi-instance via env

Instalação

$npx convez-ai solomonneas/adguard-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 3 semanas
Versão
v0.3.1
Issues abertas
8
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

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.

ToolDescription
adguard_statusServer status + protection state (GET /control/status).
adguard_statsStats window: top queries, blocked counts, clients (GET /control/stats).
adguard_query_logDNS query log slice with filters (GET /control/querylog).
adguard_list_filter_listsSubscribed blocklists + allowlists (GET /control/filtering/status).
adguard_list_user_rulesCustom user rules (GET /control/filtering/status).
adguard_list_clientsConfigured named clients (GET /control/clients).
adguard_list_blocked_services_catalogAvailable service IDs to block (GET /control/blocked_services/services).
adguard_check_hostTest what AGH would do with a hostname: filter decision, matched rules, CNAME chain, IPs (GET /control/filtering/check_host).
adguard_get_blocked_servicesGlobal blocked-services list + weekly schedule (GET /control/blocked_services/get).
adguard_get_dns_configDNS upstreams, bootstrap, cache, parallel resolution, blocking mode (GET /control/dns_info).
adguard_get_safesearch_settingsSafeSearch enabled state + per-engine flags (GET /control/safesearch/status).
adguard_sync_statusAdGuardHome Sync origin/replica status (GET /api/v1/status).
adguard_sync_healthAdGuardHome Sync health check (HEAD /healthz).
adguard_sync_logsAdGuardHome 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.

ToolDescription
adguard_add_user_ruleAppend a single user filter rule (POST /control/filtering/set_rules).
adguard_remove_user_ruleRemove a single user filter rule by exact match (POST /control/filtering/set_rules).
adguard_add_filter_listSubscribe to a new blocklist or allowlist URL (POST /control/filtering/add_url).
adguard_remove_filter_listUnsubscribe from a filter list by URL (POST /control/filtering/remove_url).
adguard_toggle_filter_listEnable or disable a subscribed filter list (POST /control/filtering/set_url).
adguard_set_client_blocked_servicesSet per-client blocked services + schedule (POST /control/clients/update).
adguard_refresh_filter_listsForce refresh subscribed filter lists immediately (POST /control/filtering/refresh).
adguard_add_clientRegister a new named client with per-client settings (POST /control/clients/add).
adguard_update_clientFull update for an existing named client; body is nested {name, data} (POST /control/clients/update).
adguard_set_blocked_servicesSet GLOBAL blocked services + optional weekly schedule; accepts HH:MM strings or ms (PUT /control/blocked_services/update).
adguard_toggle_safesearchEnable or disable SafeSearch globally with per-engine flags (PUT /control/safesearch/settings).
adguard_toggle_safebrowsingEnable or disable AGH SafeBrowsing (POST /control/safebrowsing/enable or /disable).
adguard_sync_runTrigger 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.

ToolDescription
adguard_replace_user_rulesWholesale replace the user rules block (POST /control/filtering/set_rules).
adguard_toggle_protectionEnable or disable global filtering; off stops ALL blocking (POST /control/protection).
adguard_delete_clientRemove a configured named client; per-client rules and stats are lost (POST /control/clients/delete).
adguard_clear_query_logWipe the DNS query log (POST /control/querylog_clear).
adguard_reset_statsZero the stats window (POST /control/stats_reset).
adguard_sync_clear_logsClear 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

Ver o original no GitHub

Relacionados