AdGuard Home MCP Server

MCP AdGuard Home

面向 AdGuard Home 的 MCP 服务。通过自然语言在 Cursor、Claude Code 和 Claude Desktop 中管理 DNS 过滤、客户端、DHCP、重写等功能。

功能

• 65 个工具，分为 16 个类别，涵盖完整的 AdGuard Home API
• 通过 ADGUARD_ACCESS_TIER=read-only 启用只读模式，安全地进行监控
• 通过 ADGUARD_CATEGORIES 进行类别筛选，仅开放所需工具
• 零 HTTP 依赖——使用原生 fetch（Node.js 22+）
• 在 GHCR 上提供适用于 linux/amd64 和 linux/arm64 的 Docker 镜像
• 通过 HTTP 传输提供远程 MCP（MCP_TRANSPORT=http），使用 Streamable HTTP 协议
• 使用 TypeScript/ESM，提供完整的类型安全

API 兼容性

已使用 AdGuard Home v0.107.76 测试。

快速开始

使用 npx 直接运行服务：

ADGUARD_URL="http://your-adguard-ip:3000" \
ADGUARD_USERNAME="your-username" \
ADGUARD_PASSWORD="your-password" \
npx -y @samik081/mcp-adguard-home

服务会在启动时验证与 AdGuard Home 的连接；如果缺少凭据或凭据无效，会立即报错并给出清晰的说明。

Docker

使用 Docker 运行（stdio 传输，与 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

要将其作为使用 HTTP 传输的远程 MCP 服务运行：

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

MCP 端点位于 http://localhost:3000，健康检查端点位于 http://localhost:3000/health。

配置

Claude Code CLI（推荐）：

# 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 配置（适用于 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"
      ]
    }
  }
}

远程 MCP（连接到正在运行的 Docker 容器或 HTTP 服务）：

{
  "mcpServers": {
    "adguard-home": {
      "type": "streamable-http",
      "url": "http://localhost:3000"
    }
  }
}

访问级别

使用 ADGUARD_ACCESS_TIER 环境变量控制可用工具：

级别	工具数	说明
full（默认）	65	读写——完全控制
read-only	29	只读——适合安全监控，不会更改状态

• full：全部 65 个工具。包括更改配置、添加/移除过滤器、清除日志以及所有破坏性操作。
• read-only：29 个工具。仅可查看状态和配置，以及读取查询日志，不会更改状态。

当前级别下不可用的工具不会注册到 MCP 服务中，也不会出现在 AI 工具的工具列表中，从而保持上下文整洁。

环境变量

变量	必需	默认值	描述
ADGUARD_URL	是	--	AdGuard Home 基础 URL（例如：http://192.168.1.1:3000）
ADGUARD_USERNAME	否	--	管理员用户名。如果 AdGuard Home 已禁用身份验证，则与 ADGUARD_PASSWORD 一并省略
ADGUARD_PASSWORD	否	--	管理员密码。设置了 ADGUARD_USERNAME 时必须设置
ADGUARD_ACCESS_TIER	否	full	read-only 表示仅使用只读工具，full 表示使用所有工具
ADGUARD_CATEGORIES	否	(全部)	以逗号分隔的类别允许列表（例如：dns,filtering,stats）
ADGUARD_TOOL_BLACKLIST	否	(无)	以逗号分隔的要排除的工具名称列表（例如：dns_clear_cache,stats_reset）
ADGUARD_TOOL_WHITELIST	否	(无)	以逗号分隔的要强制包含的工具名称列表，不受访问级别和类别筛选条件限制
DEBUG	否	false	启用调试日志并输出到 stderr
MCP_TRANSPORT	否	stdio	传输模式：stdio（默认）或 http
MCP_PORT	否	3000	HTTP 服务端口（仅在 MCP_TRANSPORT=http 时使用）
MCP_HOST	否	0.0.0.0	HTTP 服务绑定地址（仅在 MCP_TRANSPORT=http 时使用）
MCP_SESSION_IDLE_TIMEOUT	否	1800	HTTP 会话关闭并释放其内存前的空闲秒数（具有已连接 SSE 流的会话不会关闭）。0 表示禁用。仅在 MCP_TRANSPORT=http 时使用
MCP_EXCLUDE_TOOL_TITLES	否	false	设为 true 可在注册时省略工具标题（节省令牌）

可用类别

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

工具

mcp-adguard-home 提供 65 个按类别组织的工具。每个工具的 Access 列显示所需的最低访问级别：read-only（两个级别均可用）或 full（需要 full 级别）。Hints 列显示工具行为：read-only（不更改状态）、destructive（修改现有状态）、idempotent（调用两次结果相同）。

全局（6 个工具）

工具	描述	访问级别	提示
global_get_status	获取服务器状态，包括版本、DNS 地址、防护状态和端口	read-only	read-only、idempotent
global_get_profile	获取用户资料（名称、语言、主题）	read-only	read-only、idempotent
global_check_version	检查 AdGuard Home 更新，并与当前版本进行比较	read-only	read-only、idempotent
global_set_protection	全局启用或禁用 DNS 防护，可选择临时禁用时长	full	destructive、idempotent
global_update_profile	更新用户资料设置（名称、语言、主题）	full	destructive、idempotent
global_begin_update	启动 AdGuard Home 软件更新	full	destructive

DNS（4 个工具）

工具	描述	访问级别	提示
dns_get_info	获取完整的 DNS 配置，包括上游服务器、缓存设置、拦截模式和 DNSSEC	read-only	read-only、idempotent
dns_test_upstream	测试上游 DNS 服务器配置，验证服务器是否可访问	read-only	read-only、idempotent
dns_set_config	更新 DNS 服务器配置（23 个可选字段，支持部分更新，包括速率限制子网长度和允许列表）	full	destructive、idempotent
dns_clear_cache	清除 DNS 解析器缓存	full	destructive、idempotent

查询日志（4 个工具）

| 工具 | 描述 | 访问权限 | 提示 | |------|-------------|--------|-------| | `querylog_get` | 搜索 DNS 查询日志，可按原因或响应状态、搜索词筛选，并使用 `older_than` 游标分页（结果为空时会返回分页提示） | 只读 | 只读、幂等 | | `querylog_get_config` | 获取查询日志配置设置 | 只读 | 只读、幂等 | | `querylog_set_config` | 更新查询日志配置（启用状态、间隔、匿名化） | 完全 | 破坏性、幂等 | | `querylog_clear` | 清除整个 DNS 查询日志 | 完全 | 破坏性、幂等 |

统计（4 个工具）

工具	描述	访问权限	提示
stats_get	获取 DNS 统计数据，包括热门域名、拦截计数和客户端活动	只读	只读、幂等
stats_get_config	获取统计配置设置	只读	只读、幂等
stats_reset	重置所有 DNS 统计数据	完全	破坏性、幂等
stats_set_config	更新统计配置（启用状态、间隔、忽略的域名）	完全	破坏性、幂等

过滤（8 个工具）

工具	描述	访问权限	提示
filtering_get_status	获取过滤配置，包括拦截列表、允许列表和用户规则	只读	只读、幂等
filtering_check_host	测试当前过滤规则是否会拦截某个主机名	只读	只读、幂等
filtering_set_config	更新全局过滤配置（启用状态和更新间隔）	完全	破坏性、幂等
filtering_add_url	添加新的过滤 URL（拦截列表或允许列表）	完全	—
filtering_remove_url	从拦截列表或允许列表中移除过滤 URL	完全	破坏性
filtering_set_url	更新现有过滤 URL（重命名、更改 URL 或启用／禁用）	完全	破坏性、幂等
filtering_refresh	强制刷新过滤列表以获取最新更新	完全	破坏性、幂等
filtering_set_rules	设置自定义过滤规则（替换所有现有自定义规则）	完全	破坏性、幂等

安全浏览（2 个工具）

工具	描述	访问权限	提示
safebrowsing_get_status	获取安全浏览（恶意软件／网络钓鱼防护）状态	只读	只读、幂等
safebrowsing_set	启用或禁用安全浏览防护	完全	破坏性、幂等

家长控制（2 个工具）

工具	描述	访问权限	提示
parental_get_status	获取家长控制过滤状态	只读	只读、幂等
parental_set	启用或禁用家长控制过滤（内容限制）	完全	破坏性、幂等

安全搜索（2 个工具）

工具	描述	访问权限	提示
safesearch_get_status	获取安全搜索设置，显示各搜索引擎的强制执行状态	只读	只读、幂等
safesearch_set_settings	更新安全搜索设置并配置各搜索引擎（Bing、DuckDuckGo、Google、Pixabay、Yandex、YouTube）	完全	破坏性、幂等

客户端（5 个工具）

| 工具 | 描述 | 访问权限 | 提示 | |------|-------------|--------|-------| | `clients_get` | 获取所有已配置和自动检测到的客户端及其设置 | 只读 | 只读、幂等 | | `clients_search` | 根据客户端 ID（IP、MAC、CIDR 或客户端 ID）搜索特定客户端 | 只读 | 只读、幂等 | | `clients_add` | 添加具有单独设置的持久客户端 | 完全访问 | — | | `clients_update` | 按名称更新现有持久客户端 | 完全访问 | 有破坏性、幂等 | | `clients_delete` | 按名称删除持久客户端 | 完全访问 | 有破坏性 |

DHCP（9 个工具）

工具	描述	访问权限	提示
dhcp_get_status	获取 DHCP 服务配置、静态租约和活动租约	只读	只读、幂等
dhcp_get_interfaces	获取可用于绑定 DHCP 服务的网络接口	只读	只读、幂等
dhcp_find_active	扫描网络接口上是否存在竞争的 DHCP 服务	只读	只读、幂等
dhcp_set_config	更新 DHCP 服务配置（启用状态、接口、IPv4/IPv6 设置）	完全访问	有破坏性、幂等
dhcp_add_static_lease	添加将 MAC 地址映射到 IP 的 DHCP 静态租约	完全访问	—
dhcp_remove_static_lease	移除 DHCP 静态租约	完全访问	有破坏性
dhcp_update_static_lease	更新 DHCP 静态租约（先移除再添加）	完全访问	有破坏性、幂等
dhcp_reset	将 DHCP 配置重置为默认值	完全访问	有破坏性、幂等
dhcp_reset_leases	清除所有 DHCP 租约	完全访问	有破坏性、幂等

重写（6 个工具）

工具	描述	访问权限	提示
rewrites_list	获取所有已配置的 DNS 重写规则	只读	只读、幂等
rewrites_get_settings	获取 DNS 重写模块的启用/禁用状态	只读	只读、幂等
rewrites_add	添加新的 DNS 重写规则	完全访问	—
rewrites_update	更新 DNS 重写规则（先移除再添加）	完全访问	有破坏性、幂等
rewrites_delete	删除 DNS 重写规则	完全访问	有破坏性
rewrites_set_settings	启用或禁用 DNS 重写模块	完全访问	有破坏性、幂等

TLS（3 个工具）

工具	描述	访问权限	提示
tls_get_status	获取 TLS 配置和证书验证状态	只读	只读、幂等
tls_validate	验证 TLS 配置，不应用更改	只读	只读、幂等
tls_set_config	更新 TLS 配置，包括证书以及 HTTPS/DoH/DoT 设置	完全访问	有破坏性、幂等

已屏蔽的服务（3 个工具）

工具	描述	访问权限	提示
blocked_services_get_all	列出所有可屏蔽的服务，并按组分类	只读	只读、幂等
blocked_services_get	获取当前已屏蔽的服务列表和计划	只读	只读、幂等
blocked_services_update	更新已屏蔽的服务列表及可选计划	完全访问	有破坏性、幂等

访问控制（2 个工具）

工具	描述	访问权限	提示
access_get_list	获取访问控制列表：允许的客户端、禁止的客户端和已屏蔽的主机	只读	只读、幂等
access_set_list	设置访问控制列表，包括允许的客户端、禁止的客户端和已屏蔽的主机	完全访问	有破坏性、幂等

安装（3 个工具）

| 工具 | 描述 | 访问权限 | 提示 | |------|-------------|--------|-------| | `install_get_addresses` | 获取用于初始设置的网络接口详情和端口 | 只读 | 只读、幂等 | | `install_check_config` | 在不应用配置的情况下验证安装配置（检查 Web/DNS 绑定和凭据） | 完全 | 只读、幂等 | | `install_apply_config` | 应用初始设置配置（Web/DNS 绑定和管理员凭据） | 完全 | 有破坏性 |

移动配置（2 个工具）

工具	描述	访问权限	提示
mobile_config_get_doh	生成用于 DNS-over-HTTPS 的 Apple .mobileconfig 配置描述文件	只读	只读、幂等
mobile_config_get_dot	生成用于 DNS-over-TLS 的 Apple .mobileconfig 配置描述文件	只读	只读、幂等

验证是否正常运行

配置好 MCP 客户端后，向 AI 助手提问：

“我的 AdGuard Home 服务状态如何？”

如果连接正常，助手将调用 global_get_status，并返回服务器版本、DNS 地址、防护状态和端口配置。

使用示例

• “当前的 DNS 防护状态如何？” -- 调用 global_get_status，显示版本、地址和防护状态。
• “显示所有 DNS 重写规则” -- 调用 rewrites_list，显示所有已配置的 DNS 重写规则。
• “添加一条 DNS 重写规则，将 local.example.com 指向 192.168.1.100” -- 调用 rewrites_add，创建一条新的重写规则。

故障排除

连接错误

• 确认运行 MCP 服务的计算机可以访问 ADGUARD_URL
• 如果端口不是标准端口，请确保 URL 中包含端口（例如 http://192.168.1.1:3000）
• 检查 AdGuard Home 是否正在运行且可访问

身份验证失败

• 确认 ADGUARD_USERNAME 和 ADGUARD_PASSWORD 正确无误
• 如果 AdGuard Home 已禁用身份验证（未配置用户），请将这两个变量都留空
• 检查用户是否拥有 AdGuard Home 管理员权限

未显示工具

• 检查 ADGUARD_ACCESS_TIER 设置——read-only 模式仅公开只读工具
• 检查 ADGUARD_CATEGORIES——只会注册所列类别中的工具
• 检查标准错误输出，确认服务启动时没有报错

开发

# 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

许可证

MIT