🛡️ AdGuard Home MCP

A Model Context Protocol (MCP) server for AdGuard Home. Manage DNS rewrite records, filtering rules, and filter lists via AI agents.

📦 Installation

npm i -g @fcannizzaro/mcp-adguard-home

⚙️ Credentials

For the CLI, run:

adguard-cli login

This prompts for your AdGuard Home URL, username, and password, then saves them to ~/.config/mcp-adguard-home/config.json. Saved credentials are loaded automatically on start. If no saved credentials are available, the package falls back to these environment variables:

🚀 Configuration

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
	"mcpServers": {
		"adguard-home": {
			"command": "npx",
			"args": ["-y", "@fcannizzaro/mcp-adguard-home"],
			"env": {
				"ADGUARD_URL": "http://192.168.1.1",
				"ADGUARD_USERNAME": "admin",
				"ADGUARD_PASSWORD": "your-password"
			}
		}
	}
}

Cursor

Edit .cursor/mcp.json in your project root (or ~/.cursor/mcp.json globally):

{
	"mcpServers": {
		"adguard-home": {
			"command": "npx",
			"args": ["-y", "@fcannizzaro/mcp-adguard-home"],
			"env": {
				"ADGUARD_URL": "http://192.168.1.1",
				"ADGUARD_USERNAME": "admin",
				"ADGUARD_PASSWORD": "your-password"
			}
		}
	}
}

VS Code

Edit .vscode/mcp.json in your project root:

{
	"servers": {
		"adguard-home": {
			"type": "stdio",
			"command": "npx",
			"args": ["-y", "@fcannizzaro/mcp-adguard-home"],
			"env": {
				"ADGUARD_URL": "http://192.168.1.1",
				"ADGUARD_USERNAME": "admin",
				"ADGUARD_PASSWORD": "your-password"
			}
		}
	}
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
	"mcpServers": {
		"adguard-home": {
			"command": "npx",
			"args": ["-y", "@fcannizzaro/mcp-adguard-home"],
			"env": {
				"ADGUARD_URL": "http://192.168.1.1",
				"ADGUARD_USERNAME": "admin",
				"ADGUARD_PASSWORD": "your-password"
			}
		}
	}
}

Claude Code CLI

claude mcp add adguard-home \
  -e ADGUARD_URL=http://192.168.1.1 \
  -e ADGUARD_USERNAME=admin \
  -e ADGUARD_PASSWORD=your-password \
  -- npx -y @fcannizzaro/mcp-adguard-home

🧰 Available Tools

The package also installs a regular CLI for agents or scripts that do not use MCP:

adguard-cli login
adguard-cli list_rewrite_dns_records
adguard-cli add_rewrite_dns_record --domain example.test --ip 192.168.1.10
adguard-cli manage_dns_filtering_rules --domains ads.example --allowed false

CLI arguments can also be passed as a JSON object:

adguard-cli add_rewrite_dns_record '{"domain":"example.test","ip":"192.168.1.10"}'

DNS Rewrite Records

DNS Filtering Rules

Filter Lists

📄 License

Licensed under the MIT License.