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.

Disclaimer: Most of this code has been AI-generated and has not been fully tested yet. I created this project for my own needs and plan to continue improving its quality, but it may be buggy in the early stages. If you find a bug, feel free to open an issue -- I'll try to work on it in my spare time.

Features

• 65 tools across 16 API 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

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:

• 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

Available Categories

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

Tools

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