MCP Adguard Home

](https://www.npmjs.com/package/@samik081/mcp-adguard-home) ](https://ghcr.io/samik081/mcp-adguard-home)  ](https://nodejs.org)

MCP AdGuard主页

MCP服务器 AdGuard主页.通过Cursor、Claude Code和Claude Desktop中的自然语言管理DNS过滤、客户端、DHCP、重写等。

特性

• 65工具 穿过 16个类别 涵盖完整的AdGuard Home API
• 只读模式 通过 ADGUARD_ACCESS_TIER=read-only 用于安全监测
• 类别筛选 通过 ADGUARD_CATEGORIES 仅公开您需要的工具
• 零HTTP依赖 --使用本地 fetch （Node.js 18+）
• Docker镜像 为了 linux/amd64 和 linux/arm64 上 GHCR
• 远程MCP 通过HTTP传输(MCP_TRANSPORT=http)使用流式HTTP协议
• Types/ESM 具有全类型安全性

API兼容性

使用AdGuard Home进行测试 v0.107.72.

快速开始

使用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运行（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命令行界面（推荐）：

# 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_config.json，光标 .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（标准操作系统）：

{
  "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 环境变量：

• 满的：全部65个工具。包括配置更改、添加/删除筛选器、清除日志和所有破坏性操作。
• 只读：29个工具。状态、配置查看和查询日志只读。没有状态变化。

您层中不可用的工具未在MCP服务器上注册。它们不会出现在你的人工智能工具的工具列表中，保持上下文干净。

环境变量

可用类别

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

工具

mcp adguard home提供按类别组织的65个工具。每个工具的“访问”列显示了所需的最低级别： read-only （两层都有）或 full （要求 full 层）。提示列显示工具行为： read-only （无状态变化）， destructive （修改现有状态）， idempotent （如果调用两次，结果相同）。

Global (6 tools)

DNS (4 tools)

Query Log (4 tools)

Statistics (4 tools)

Filtering (8 tools)

Safe Browsing (2 tools)

Parental (2 tools)

Safe Search (2 tools)

Clients (5 tools)

DHCP (9 tools)

Rewrites (6 tools)

TLS (3 tools)

Blocked Services (3 tools)

Access (2 tools)

Install (3 tools)

Mobile Config (2 tools)

验证它是否有效

配置完MCP客户端后，询问您的AI助手：

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

如果连接正常，助理会打电话 global_get_status 并返回您的服务器版本、DNS地址、保护状态和端口配置。

用法示例

• “当前的DNS保护状态如何？” --电话 global_get_status 显示版本、地址和保护状态。
• “显示所有DNS重写规则” --电话 rewrites_list 显示所有配置的DNS重写。
• “为local.example.com添加指向192.168.1.100的DNS重写” --电话 rewrites_add 创建新的重写规则。

故障排除

连接错误

• 验证 ADGUARD_URL 可从运行MCP服务器的计算机访问
• 如果非标准（例如。， http://192.168.1.1:3000)
• 检查AdGuard主页是否正在运行且可访问

身份验证失败

• 验证 ADGUARD_USERNAME 和 ADGUARD_PASSWORD 是正确的
• 检查用户在AdGuard主页中是否具有管理员权限

工具未显示

• 检查你的 ADGUARD_ACCESS_TIER 设置-- read-only 模式仅公开读取工具
• 检查 ADGUARD_CATEGORIES --仅注册所列类别中的工具
• 通过检查stderr输出，验证服务器是否已正确启动

发展

# 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

许可证

麻省理工学院