Metadata-Version: 2.4
Name: adguard-home-mcp
Version: 0.2.0
Summary: MCP server for AdGuard Home — wraps the local REST API. Supports stdio and streamable HTTP.
Project-URL: Homepage, https://github.com/danielrosehill/AdGuard-Home-MCP
Project-URL: Issues, https://github.com/danielrosehill/AdGuard-Home-MCP/issues
Author: Daniel Rosehill
License: MIT
Keywords: adguard,adguard-home,dns,mcp,model-context-protocol
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.10.0
Requires-Dist: pydantic>=2
Description-Content-Type: text/markdown

# AdGuard-Home-MCP

MCP server wrapping the [AdGuard Home](https://github.com/AdguardTeam/AdGuardHome) 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

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

### Streamable HTTP (Docker)

```bash
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)

```json
{
  "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

```json
{
  "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.
