npm package: @samik081/mcp-adguard-home
Description: Manage AdGuard Home through AI assistants
Latest version: 0.7.0

[![npm version](https://img.shields.io/npm/v/@samik081/mcp-adguard-home)](https://www.npmjs.com/package/@samik081/mcp-adguard-home)
[![Docker image](https://ghcr-badge.egpl.dev/samik081/mcp-adguard-home/latest_tag?trim=major&label=docker)](https://ghcr.io/samik081/mcp-adguard-home)
[![License: MIT](https://img.shields.io/npm/l/@samik081/mcp-adguard-home)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/node/v/@samik081/mcp-adguard-home)](https://nodejs.org)

# MCP AdGuard Home

MCP server for [AdGuard Home](https://adguard.com/pl/adguard-home/overview.html). 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](https://ghcr.io/samik081/mcp-adguard-home)
- **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.72**.

## Quick Start

Run the server directly with npx:

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

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

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

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

```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):**

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

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

<details>
<summary>Global (6 tools)</summary>

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

</details>

<details>
<summary>DNS (4 tools)</summary>

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

</details>

<details>
<summary>Query Log (4 tools)</summary>

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

</details>

<details>
<summary>Statistics (4 tools)</summary>

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

</details>

<details>
<summary>Filtering (8 tools)</summary>

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

</details>

<details>
<summary>Safe Browsing (2 tools)</summary>

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

</details>

<details>
<summary>Parental (2 tools)</summary>

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

</details>

<details>
<summary>Safe Search (2 tools)</summary>

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

</details>

<details>
<summary>Clients (5 tools)</summary>

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

</details>

<details>
<summary>DHCP (9 tools)</summary>

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

</details>

<details>
<summary>Rewrites (6 tools)</summary>

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

</details>

<details>
<summary>TLS (3 tools)</summary>

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

</details>

<details>
<summary>Blocked Services (3 tools)</summary>

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

</details>

<details>
<summary>Access (2 tools)</summary>

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

</details>

<details>
<summary>Install (3 tools)</summary>

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

</details>

<details>
<summary>Mobile Config (2 tools)</summary>

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

</details>

## 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

```bash
# 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](LICENSE)