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.
Metadata
Release files for adguard-home-mcp 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| adguard_home_mcp-0.2.0.tar.gz | 6.3 kB | Without provenance | Details for adguard_home_mcp-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| adguard_home_mcp-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for adguard_home_mcp-0.2.0-py3-none-any.whl |
Total release size: 14.1 kB
Release files / adguard_home_mcp-0.2.0.tar.gz
| Download URL | adguard_home_mcp-0.2.0.tar.gz |
|---|---|
| Size | 6.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
294f9b81a0dc7e338a1b6550cb5629d150404a70c88e1c6ad4004ae234eb41f0
|
|
BLAKE2b-256 checksum How to use checksums |
f5fdeb68e16426df57dfc9e6d752bfafb1df66f9155d519913d8af6bb7e5b76b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.8
|
Release files / adguard_home_mcp-0.2.0-py3-none-any.whl
| Download URL | adguard_home_mcp-0.2.0-py3-none-any.whl |
|---|---|
| Size | 7.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e696ac212d9bfe88ea0011e5e0e44b79b0f2ca18abb53974e3178c2eeab04a68
|
|
BLAKE2b-256 checksum How to use checksums |
b5c022fcc909b31ee58aff1c0ba82ef315d328099bbe073ecd28aa2d16d34566
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.8
|
Security for adguard-home-mcp 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.