🛡️ AdGuard Home MCP

🛡️ AdGuard Home MCP

适用于 AdGuard Home 的 Model Context Protocol（MCP）服务。通过 AI Agent 管理 DNS 重写记录、过滤规则和过滤列表。

📦 安装

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

⚙️ 凭据

对于 CLI，请运行：

adguard-cli login

系统会提示你输入 AdGuard Home URL、用户名和密码，然后将其保存到 ~/.config/mcp-adguard-home/config.json。启动时会自动加载已保存的凭据。如果没有可用的已保存凭据，程序包会回退到以下环境变量：

变量	说明
ADGUARD_URL	AdGuard Home 实例的基础 URL（例如 http://192.168.1.1）
ADGUARD_USERNAME	AdGuard Home 用户名
ADGUARD_PASSWORD	AdGuard Home 密码

🚀 配置

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %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

编辑项目根目录中的 .cursor/mcp.json（或全局配置文件 ~/.cursor/mcp.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"
			}
		}
	}
}

VS Code

编辑项目根目录中的 .vscode/mcp.json：

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

编辑 ~/.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

🧰 可用工具

该程序包还会安装一个常规 CLI，供不使用 MCP 的 Agent 或脚本使用：

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 参数也可以作为 JSON 对象传入：

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

DNS 重写记录

工具	说明	参数
list_rewrite_dns_records	列出所有 DNS 重写记录	—
add_rewrite_dns_record	添加 DNS 重写记录	domain: string、ip: string
remove_rewrite_dns_record	移除 DNS 重写记录	domain: string、ip: string

DNS 过滤规则

工具	说明	参数
list_dns_filtering_rules	列出所有自定义 DNS 过滤规则	—
manage_dns_filtering_rules	屏蔽或允许域名	domains: string[]、allowed: boolean
remove_rdns_filtering_rules	移除自定义过滤规则	domains: string[]

过滤列表

工具	说明	参数
list_filter_lists	列出所有已配置的过滤列表	—
toggle_filter_list	启用或停用过滤列表	id: number、enabled: boolean
refresh_filter_lists	强制更新所有过滤列表	—

📄 许可证

基于 MIT License 许可。