npm version Docker image License: MIT Node.js Version

MCP AdGuard Home

MCP server for AdGuard Home. Manage DNS filtering, clients, DHCP, rewrites, and more through natural language in Cursor, Claude Code, and Claude Desktop.

Features

• 65 tools across 16 categories covering the complete AdGuard Home API
• Read-only mode via ADGUARD_ACCESS_TIER=read-only for safe monitoring
• Category filtering via ADGUARD_CATEGORIES to expose only the tools you need
• Zero HTTP dependencies -- uses native fetch (Node.js 18+)
• Docker images for linux/amd64 and linux/arm64 on GHCR
• Remote MCP via HTTP transport (MCP_TRANSPORT=http) using the Streamable HTTP protocol
• TypeScript/ESM with full type safety

API Compatibility

Tested with AdGuard Home v0.107.76.

Quick Start

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.

Docker

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.

Configuration

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"
    }
  }
}

Access Tiers

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

• full: All 65 tools. Includes configuration changes, adding/removing filters, clearing logs, and all destructive operations.
• read-only: 29 tools. Status, configuration viewing, and query log reading only. 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.

Environment Variables

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)

Available Categories

global, dns, querylog, stats, filtering, safebrowsing, parental, safesearch, clients, dhcp, rewrites, tls, blocked_services, access, install, mobile_config

Tools

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).

Global (6 tools)

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

DNS (4 tools)

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

Query Log (4 tools)

Tool	Description	Access	Hints
querylog_get	Search DNS query log with optional filtering by reason or 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

Statistics (4 tools)

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

Filtering (8 tools)

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

Safe Browsing (2 tools)

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

Parental (2 tools)

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

Safe Search (2 tools)

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

Clients (5 tools)

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

DHCP (9 tools)

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

Rewrites (6 tools)

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

TLS (3 tools)

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

Blocked Services (3 tools)

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

Access (2 tools)

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

Install (3 tools)

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

Mobile Config (2 tools)

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

Verify It Works

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.

Usage Examples

• "What's the current DNS protection status?" -- calls global_get_status to show version, addresses, and protection state.
• "Show me all DNS rewrite rules" -- calls rewrites_list to display all configured DNS rewrites.
• "Add a DNS rewrite for local.example.com pointing to 192.168.1.100" -- calls rewrites_add to create a new rewrite rule.

Troubleshooting

Connection errors

• Verify ADGUARD_URL is reachable from the machine running the MCP server
• Ensure the URL includes the port if non-standard (e.g., http://192.168.1.1:3000)
• Check that AdGuard Home is running and accessible

Authentication failures

• Verify ADGUARD_USERNAME and ADGUARD_PASSWORD are correct
• Check that the user has admin privileges in AdGuard Home

Tools not showing up

• Check your ADGUARD_ACCESS_TIER setting -- read-only mode only exposes read tools
• Check ADGUARD_CATEGORIES -- only tools in listed categories are registered
• Verify the server started without errors by checking stderr output

Development

# 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

License

MIT