controld-mcp
Control D MCP
一个本地 Model Context Protocol 服务器,用于通过对话安全地管理 Control D。
它可以检查配置文件和端点,诊断最近被阻止的 DNS 查询,临时暂停配置文件,创建阻止/绕过/重定向规则,以及删除规则。每次实时策略更改都需要 confirm: true,并且之后会进行回读检查。
设置
需要 Node.js 20 或更高版本,以及一个专用的 Control D 写入令牌。尽可能在 Control D 中将令牌限制为受信任的源 IP。
npm install
npm run test将令牌放在 ~/.config/controld-mcp.env 中(切勿放在此仓库中),并将文件模式设置为 0600:
CONTROL_D_API_TOKEN=your-dedicated-write-token示例 Codex 配置:
[mcp_servers.controld]
command = "/absolute/path/to/node"
args = ["/absolute/path/to/controld-mcp/dist/index.js"]添加服务器后重启 MCP 主机。 MCP 进程可以在没有令牌的情况下启动,但在令牌存在并重启主机之前,其工具将返回设置错误。
Related MCP server: technitium-mcp-secure
典型流程
“显示我的 Control D 配置文件。”
“我刚刚尝试了 example.com。过去五分钟内阻止了什么?”
查看查询时间戳以及触发每个阻止的规则/过滤器。
“为
cdn.example.net在 Global 上创建一个 30 分钟的临时绕过。”助手会显示确切提议的变更,并在调用确认的写入工具之前请求批准。
对于路由:先列出代理位置,然后将精确域名规则或命名服务重定向到精确的位置 ID。像 YouTube 这样的服务可能涉及许多变化的域名,因此 set_service_policy 通常比手动维护其主机名更安全。
安全设计
没有通用的 HTTP/API 直通工具。
API 和分析主机仅限于 Control D。
令牌在运行时加载,从不返回或记录。
活动日志请求限制为 200 行,并且从不缓存。
写入需要精确的配置文件解析和
confirm: true。优先使用精确域名而不是通配符。在解除任何阻止之前检查结果。
API 稳定性
Control D 警告其 API 未版本化。活动日志和若干管理操作使用当前的第一方仪表板契约,因为它们并非全部出现在公共 API 参考中。请参阅 docs/api-contracts.md。
致谢
端点行为已与 Control D 官方仪表板和社区 Control D Manager Home Assistant 集成 进行了交叉检查。本项目是一个独立的实现。
许可证
MIT
Available Tools
15 toolscheck_setupCheck Control D connectionARead-onlyIdempotent
Validate the token and report account capabilities without revealing the token.
Inputs: no named parameters.
create_block_rulesBlock domainsADestructive
Create enabled custom block rules. Requires confirm=true.
Inputs: confirm (required), profile (required), hostnames (required), comment, +1 more.
create_bypass_rulesUnblock domainsADestructive
Create enabled custom bypass rules. Use exact domains first; wildcards are broader. Requires confirm=true.
Inputs: confirm (required), profile (required), hostnames (required), comment, +1 more.
create_redirect_rulesRedirect domainsADestructive
Redirect matching domains through a Control D proxy location. Use list_proxy_locations first. Requires confirm=true.
Inputs: confirm (required), profile (required), hostnames (required), proxyLocationId (required), +2 more.
delete_rulesDelete custom rulesADestructive
Delete rules by exact hostname. This is destructive and requires confirm=true.
Inputs: confirm (required), profile (required), hostnames (required).
diagnose_recent_blocksDiagnose a blocked websiteBRead-onlyIdempotent
Find DNS queries blocked in the recent browsing window. Supply the site you tried; dependent domains may appear separately in the results.
Inputs: site (required), limit, search, minutes, +1 more.
get_recent_activityGet recent DNS activityARead-onlyIdempotent
Read recent Control D activity. Activity logs require Full Analytics and are sensitive; results are not stored.
Inputs: limit, search, minutes, endpointId, +1 more.
list_endpointsList Control D endpointsARead-onlyIdempotent
List devices/endpoints with recent activity metadata.
Inputs: no named parameters.
list_profile_rulesList custom rulesARead-onlyIdempotent
List all custom rules for one profile.
Inputs: profile (required).
list_profilesList Control D profilesARead-onlyIdempotent
List profiles and their current pause state.
Inputs: no named parameters.
list_profile_servicesList service policiesARead-onlyIdempotent
List the current profile service states plus the service catalog. Use this to resolve names such as YouTube to exact IDs.
Inputs: profile (required).
list_proxy_locationsList redirect locationsARead-onlyIdempotent
List Control D proxy locations and IDs for redirect rules.
Inputs: no named parameters.
pause_profileTemporarily pause Control DADestructive
Pause all enforcement on a profile for a bounded time. This changes live DNS behavior and requires confirm=true.
Inputs: confirm (required), minutes (required), profile (required).
resume_profileResume Control DADestructive
Immediately resume a paused profile. Requires confirm=true.
Inputs: confirm (required), profile (required).
set_service_policySet service policyADestructive
Turn a named service off, block it, bypass it, or route it through a Control D proxy location. Service rules can cover changing domain sets and override filters. Requires confirm=true.
Inputs: mode (required), confirm (required), profile (required), service (required), +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Each tool has a distinct purpose: list tools target different entities (profiles, endpoints, locations, rules, services), create tools specify rule types, and activity/diagnose tools are clearly separated. No overlapping or ambiguous tools.
Most tools follow the verb_noun pattern (e.g., list_profiles, create_block_rules), but there is a mix of verbs like 'get', 'diagnose', and 'check' alongside 'list'. This is mildly inconsistent but still clear enough to avoid confusion.
With 15 tools, the server sits at the upper boundary of the recommended range but remains well-suited for a DNS control service. The tool count is neither excessive nor insufficient for the domain.
The tool set covers listing, creating, deleting, and modifying state (pause/resume/set), plus diagnostics and setup checks. No obvious missing operations for the Control D domain.
Maintenance
Related MCP Connectors
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
MCP server for DNSimple — domains, DNS zone records, availability, pricing and contacts.
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceMCP server for managing AdGuard Home instances and AdGuardHome Sync with 33 tools across read, safe-write, and destructive operations, featuring three-tier write gating.88 npm2MIT
- AlicenseAqualityDmaintenanceA security-hardened MCP server for managing Technitium DNS Server via its HTTP API, offering tools for DNS zones, records, blocking, cache, settings, and diagnostics.39MIT
- AlicenseDqualityBmaintenanceMCP server for Porkbun domains and DNS, enabling read-only and mutating operations with safety features like dry-run and write mode toggle.40115 npm3MIT
- AlicenseNot gradedqualityBmaintenanceMCP server for AI agents to safely manage Cloudflare DNS, DMARC, SPF, BIMI, and Email Routing with dry-run-first and approval-based writes.10MIT