Manage AdGuard Home through AI assistants
Valid MCP server (1 strong, 1 medium validity signals). No known CVEs in dependencies. Package registry verified. Imported from the Official MCP Registry. Trust signals: trusted author (7/7 approved).
5 files analyzed · 1 issue found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
Set these up before or after installing:
Environment variable: ADGUARD_URL
Environment variable: ADGUARD_USERNAME
Environment variable: ADGUARD_PASSWORD
Add this to your MCP configuration file:
{
"mcpServers": {
"io-github-samik081-mcp-adguard-home": {
"env": {
"ADGUARD_URL": "your-adguard-url-here",
"ADGUARD_PASSWORD": "your-adguard-password-here",
"ADGUARD_USERNAME": "your-adguard-username-here"
},
"args": [
"-y",
"@samik081/mcp-adguard-home"
],
"command": "npx"
}
}
}From the project's GitHub README.
MCP server for AdGuard Home. Manage DNS filtering, clients, DHCP, rewrites, and more through natural language in Cursor, Claude Code, and Claude Desktop.
ADGUARD_ACCESS_TIER=read-only for safe monitoringADGUARD_CATEGORIES to expose only the tools you needfetch (Node.js 18+)linux/amd64 and linux/arm64 on GHCRMCP_TRANSPORT=http) using the Streamable HTTP protocolTested with AdGuard Home v0.107.72.
Run the server directly with npx:
ADGUARD_URL="http://your-adguard-ip:3000" \
ADGUARD_USERNAME="your-username" \
ADGUARD_PASSWORD="your-password" \
npx -y @samik081/mcp-adguard-home
The server validates your AdGuard Home connection on startup and fails immediately with a clear error if credentials are missing or invalid.
Run with Docker (stdio transport, same as npx):
docker run --rm -i \
-e ADGUARD_URL=http://your-adguard-ip:3000 \
-e ADGUARD_USERNAME=your-username \
-e ADGUARD_PASSWORD=your-password \
ghcr.io/samik081/mcp-adguard-home
To run as a remote MCP server with HTTP transport:
docker run -d -p 3000:3000 \
-e MCP_TRANSPORT=http \
-e ADGUARD_URL=http://your-adguard-ip:3000 \
-e ADGUARD_USERNAME=your-username \
-e ADGUARD_PASSWORD=your-password \
ghcr.io/samik081/mcp-adguard-home
The MCP endpoint is available at http://localhost:3000 and a health check at http://localhost:3000/health.
Claude Code CLI (recommended):
# Using npx
claude mcp add --transport stdio adguard-home \
--env ADGUARD_URL=http://your-adguard-ip:3000 \
--env ADGUARD_USERNAME=your-username \
--env ADGUARD_PASSWORD=your-password \
-- npx -y @samik081/mcp-adguard-home
# Using Docker
claude mcp add --transport stdio adguard-home \
--env ADGUARD_URL=http://your-adguard-ip:3000 \
--env ADGUARD_USERNAME=your-username \
--env ADGUARD_PASSWORD=your-password \
-- docker run --rm -i ghcr.io/samik081/mcp-adguard-home
# Using remote HTTP (connect to a running Docker container or HTTP server)
claude mcp add --transport http adguard-home http://localhost:3000
JSON config (works with Claude Code .mcp.json, Claude Desktop claude_desktop_config.json, Cursor .cursor/mcp.json):
{
"mcpServers": {
"adguard-home": {
"command": "npx",
"args": ["-y", "@samik081/mcp-adguard-home"],
"env": {
"ADGUARD_URL": "http://your-adguard-ip:3000",
"ADGUARD_USERNAME": "your-username",
"ADGUARD_PASSWORD": "your-password"
}
}
}
}
Docker (stdio):
{
"mcpServers": {
"adguard-home": {
"command": "docker",
"args": ["run", "--rm", "-i",
"-e", "ADGUARD_URL=http://your-adguard-ip:3000",
"-e", "ADGUARD_USERNAME=your-username",
"-e", "ADGUARD_PASSWORD=your-password",
"ghcr.io/samik081/mcp-adguard-home"
]
}
}
}
Remote MCP (connect to a running Docker container or HTTP server):
{
"mcpServers": {
"adguard-home": {
"type": "streamable-http",
"url": "http://localhost:3000"
}
}
}
Control which tools are available using the ADGUARD_ACCESS_TIER environment variable:
| Tier | Tools | Description |
|---|---|---|
full (default) | 65 | Read and write -- full control |
read-only | 29 | Read only -- safe for monitoring, no state changes |
Tools that are not available in your tier are not registered with the MCP server. They will not appear in your AI tool's tool list, keeping the context clean.
| Variable | Required | Default | Description |
|---|---|---|---|
ADGUARD_URL | Yes | -- | AdGuard Home base URL (e.g., http://192.168.1.1:3000) |
ADGUARD_USERNAME | Yes | -- | Admin username |
ADGUARD_PASSWORD | Yes | -- | Admin password |
ADGUARD_ACCESS_TIER | No | full | read-only for read-only tools only, full for all tools |
ADGUARD_CATEGORIES | No | (all) | Comma-separated category allowlist (e.g., dns,filtering,stats) |
ADGUARD_TOOL_BLACKLIST | No | (none) | Comma-separated list of tool names to exclude (e.g., dns_clear_cache,stats_reset) |
ADGUARD_TOOL_WHITELIST | No | (none) | Comma-separated list of tool names to force-include, bypassing access tier and category filters |
DEBUG | No | false | Enable debug logging to stderr |
MCP_TRANSPORT | No | stdio | Transport mode: stdio (default) or http |
MCP_PORT | No | 3000 | HTTP server port (only used when MCP_TRANSPORT=http) |
MCP_HOST | No | 0.0.0.0 | HTTP server bind address (only used when MCP_TRANSPORT=http) |
MCP_EXCLUDE_TOOL_TITLES | No | false | Set true to omit tool titles from registration (saves tokens) |
global, dns, querylog, stats, filtering, safebrowsing, parental, safesearch, clients, dhcp, rewrites, tls, blocked_services, access, install, mobile_config
mcp-adguard-home provides 65 tools organized by category. Each tool's Access column shows the minimum tier required: read-only (available in both tiers) or full (requires full tier). The Hints column shows tool behavior: read-only (no state changes), destructive (modifies existing state), idempotent (same result if called twice).
| Tool | Description | Access | Hints |
|---|---|---|---|
global_get_status | Retrieve server status including version, DNS addresses, protection state, and ports | read-only | read-only, idempotent |
global_get_profile | Retrieve user profile (name, language, theme) | read-only | read-only, idempotent |
global_check_version | Check for AdGuard Home updates and compare with current version | read-only | read-only, idempotent |
global_set_protection | Enable or disable DNS protection globally, with optional duration for temporary disable | full | destructive, idempotent |
global_update_profile | Update user profile settings (name, language, theme) | full | destructive, idempotent |
global_begin_update | Initiate an AdGuard Home software update | full | destructive |
| Tool | Description | Access | Hints |
|---|---|---|---|
dns_get_info | Retrieve full DNS configuration including upstreams, cache settings, blocking mode, and DNSSEC | read-only | read-only, idempotent |
dns_test_upstream | Test upstream DNS server configuration to verify servers are reachable | read-only | read-only, idempotent |
dns_set_config | Update DNS server configuration (19 optional fields for partial update) | full | destructive, idempotent |
dns_clear_cache | Clear the DNS resolver cache | full | destructive, idempotent |
| Tool | Description | Access | Hints |
|---|---|---|---|
querylog_get | Search DNS query log with optional filtering by response status, search term, and pagination | read-only | read-only, idempotent |
querylog_get_config | Retrieve query log configuration settings | read-only | read-only, idempotent |
querylog_set_config | Update query log configuration (enabled, interval, anonymization) | full | destructive, idempotent |
querylog_clear | Clear the entire DNS query log | full | destructive, idempotent |
| Tool | Description | Access | Hints |
|---|---|---|---|
stats_get | Retrieve DNS statistics including top domains, blocked counts, and client activity | read-only | read-only, idempotent |
stats_get_config | Retrieve statistics configuration settings | read-only | read-only, idempotent |
stats_reset | Reset all DNS statistics | full | destructive, idempotent |
stats_set_config | Update statistics configuration (enabled, interval, ignored domains) | full | destructive, idempotent |
| Tool | Description | Access | Hints |
|---|---|---|---|
filtering_get_status | Retrieve filtering configuration including blocklists, allowlists, and user rules | read-only | read-only, idempotent |
filtering_check_host | Test whether a hostname would be blocked by current filtering rules | read-only | read-only, idempotent |
filtering_set_config | Update global filtering configuration (enabled state and update interval) | full | destructive, idempotent |
filtering_add_url | Add a new filter URL (blocklist or allowlist) | full | — |
filtering_remove_url | Remove a filter URL from blocklist or allowlist | full | destructive |
filtering_set_url | Update an existing filter URL (rename, change URL, or enable/disable) | full | destructive, idempotent |
filtering_refresh | Force refresh of filter lists to fetch latest updates | full | destructive, idempotent |
filtering_set_rules | Set custom filtering rules (replaces all existing custom rules) | full | destructive, idempotent |
| Tool | Description | Access | Hints |
|---|---|---|---|
safebrowsing_get_status | Retrieve safe browsing (malware/phishing protection) status | read-only | read-only, idempotent |
safebrowsing_set | Enable or disable safe browsing protection | full | destructive, idempotent |
| Tool | Description | Access | Hints |
|---|---|---|---|
parental_get_status | Retrieve parental filtering status | read-only | read-only, idempotent |
parental_set | Enable or disable parental filtering (content restrictions) | full | destructive, idempotent |
| Tool | Description | Access | Hints |
|---|---|---|---|
safesearch_get_status | Retrieve safe search settings showing per-engine enforcement status | read-only | read-only, idempotent |
safesearch_set_settings | Update safe search settings with per-engine configuration (Bing, DuckDuckGo, Google, Pixabay, Yandex, YouTube) | full | destructive, idempotent |
| Tool | Description | Access | Hints |
|---|---|---|---|
clients_get | Retrieve all configured and auto-detected clients with their settings | read-only | read-only, idempotent |
clients_search | Search for specific clients by their IDs (IP, MAC, CIDR, or client ID) | read-only | read-only, idempotent |
clients_add | Add a new persistent client with per-client settings | full | — |
clients_update | Update an existing persistent client by name | full | destructive, idempotent |
clients_delete | Delete a persistent client by name | full | destructive |
| Tool | Description | Access | Hints |
|---|---|---|---|
dhcp_get_status | Retrieve DHCP server configuration, static leases, and active leases | read-only | read-only, idempotent |
dhcp_get_interfaces | Retrieve available network interfaces for DHCP server binding | read-only | read-only, idempotent |
dhcp_find_active | Scan for competing DHCP servers on a network interface | read-only | read-only, idempotent |
dhcp_set_config | Update DHCP server configuration (enabled state, interface, IPv4/IPv6 settings) | full | destructive, idempotent |
dhcp_add_static_lease | Add a static DHCP lease mapping a MAC address to an IP | full | — |
dhcp_remove_static_lease | Remove a static DHCP lease | full | destructive |
dhcp_update_static_lease | Update a static DHCP lease (remove + add pattern) | full | destructive, idempotent |
dhcp_reset | Reset DHCP configuration to defaults | full | destructive, idempotent |
dhcp_reset_leases | Clear all DHCP leases | full | destructive, idempotent |
| Tool | Description | Access | Hints |
|---|---|---|---|
rewrites_list | Retrieve all configured DNS rewrite rules | read-only | read-only, idempotent |
rewrites_get_settings | Retrieve DNS rewrite module enabled/disabled state | read-only | read-only, idempotent |
rewrites_add | Add a new DNS rewrite rule | full | — |
rewrites_update | Update a DNS rewrite rule (remove + add pattern) | full | destructive, idempotent |
rewrites_delete | Delete a DNS rewrite rule | full | destructive |
rewrites_set_settings | Enable or disable the DNS rewrite module | full | destructive, idempotent |
| Tool | Description | Access | Hints |
|---|---|---|---|
tls_get_status | Retrieve TLS configuration and certificate validation status | read-only | read-only, idempotent |
tls_validate | Validate TLS configuration without applying changes | read-only | read-only, idempotent |
tls_set_config | Update TLS configuration including certificates and HTTPS/DoH/DoT settings | full | destructive, idempotent |
| Tool | Description | Access | Hints |
|---|---|---|---|
blocked_services_get_all | List all available services that can be blocked, organized by group | read-only | read-only, idempotent |
blocked_services_get | Retrieve currently blocked services list and schedule | read-only | read-only, idempotent |
blocked_services_update | Update the list of blocked services and optional schedule | full | destructive, idempotent |
| Tool | Description | Access | Hints |
|---|---|---|---|
access_get_list | Retrieve access control lists: allowed clients, disallowed clients, and blocked hosts | read-only | read-only, idempotent |
access_set_list | Set access control lists for allowed clients, disallowed clients, and blocked hosts | full | destructive, idempotent |
| Tool | Description | Access | Hints |
|---|---|---|---|
install_get_addresses | Retrieve network interface details and ports for initial setup | read-only | read-only, idempotent |
install_check_config | Validate install configuration without applying (checks web/DNS binding, credentials) | full | read-only, idempotent |
install_apply_config | Apply initial setup configuration (web/DNS binding and admin credentials) | full | destructive |
| Tool | Description | Access | Hints |
|---|---|---|---|
mobile_config_get_doh | Generate Apple .mobileconfig profile for DNS-over-HTTPS | read-only | read-only, idempotent |
mobile_config_get_dot | Generate Apple .mobileconfig profile for DNS-over-TLS | read-only | read-only, idempotent |
After configuring your MCP client, ask your AI assistant:
"What's my AdGuard Home server status?"
If the connection is working, the assistant will call global_get_status and return your server version, DNS addresses, protection state, and port configuration.
global_get_status to show version, addresses, and protection state.rewrites_list to display all configured DNS rewrites.rewrites_add to create a new rewrite rule.ADGUARD_URL is reachable from the machine running the MCP serverhttp://192.168.1.1:3000)ADGUARD_USERNAME and ADGUARD_PASSWORD are correctADGUARD_ACCESS_TIER setting -- read-only mode only exposes read toolsADGUARD_CATEGORIES -- only tools in listed categories are registered# Install dependencies
npm install
# Build the project
npm run build
# Run in development mode (auto-reload)
npm run dev
# Open the MCP Inspector for interactive testing
npm run inspect
Be the first to review this server!
by Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
by Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
by mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.
by Microsoft · Content & Media
Convert files (PDF, Word, Excel, images, audio) to Markdown for LLM consumption
by mcp-marketplace · Developer Tools
Scaffold, build, and publish TypeScript MCP servers to npm — conversationally
by mcp-marketplace · Finance
Free stock data and market news for any MCP-compatible AI assistant.