内容
# mcp-technitium-dns
专注于安全性的MCP服务器，用于通过Technitium HTTP API查询和管理Technitium DNS服务器。Codex或其他MCP客户端使用命名Bearer令牌向此服务器进行身份验证；此服务器使用Technitium API令牌在`Authorization: Bearer ...`头部与Technitium进行身份验证。Technitium凭证从未暴露给MCP客户端。
记录工具使用严格、验证的snake_case输入，并将它们映射到Technitium API参数。例如，A记录使用`record: { ip_address: "192.0.2.10", ttl: 3600 }`；MX记录使用`record: { preference: 10, exchange: "mail.example.com" }`。
区域导出使用Technitium所需的具有单个使用API令牌的GET端点，该令牌在导出前立即创建。
`READ_ONLY=true`注册仅限读取的工具。写入工具需要读写MCP Bearer令牌，破坏性工具需要`confirm: true`。
## Technitium 设置
目标：带有基于API令牌自动化的Technitium DNS服务器。
- 尽可能使用HTTPS进行Technitium。
- 如果Technitium仅在HTTP上可用，请设置`TECHNITIUM_ALLOW_HTTP_LOCAL=true`；目标主机必须仍然是本地/私有，除非它明确列在`TECHNITIUM_ALLOW_HTTP_HOSTNAMES`中。
- 为MCP自动化创建专用的Technitium用户。
- 仅授予您的预期工具所需的权限。
- 将Technitium API令牌存储在受保护的文件中，并在生产部署中使用`TECHNITIUM_API_TOKEN_FILE`。
- 当服务器应仅公开只读MCP工具时，设置`READ_ONLY=true`。
## 创建 Technitium API 令牌
1. 以管理员身份登录到Technitium DNS网页控制台。
2. 为MCP自动化创建专用用户，或使用现有的专用自动化用户。
3. 仅授予您的预期工具所需的权限。只读使用需要Dashboard、Zones、Cache、Allowed、Blocked、Apps、DNS Client、Settings、Administration、DHCP Server和Logs的查看权限。写入使用需要您要管理的部分的修改/删除权限。
4. 打开该帐户的用户菜单/个人资料，并使用清晰的令牌名称创建API令牌，例如`mcp-technitium-dns`。
5. 立即复制生成的令牌。
6. 将其存储在受保护的文件中，并配置`TECHNITIUM_API_TOKEN_FILE`，或为本地测试设置`TECHNITIUM_API_TOKEN`。
API令牌作为`Authorization: Bearer <token>`传递给Technitium。不要在此MCP服务器中配置Technitium用户名/密码。
## 安全模型
- 默认情况下，此MCP服务器使用HTTPS。
- 除非`TECHNITIUM_ALLOW_HTTP_LOCAL=true`且目标主机是本地/私有，否则Technitium `TECHNITIUM_BASE_URL`必须使用HTTPS。
- 写入工具需要读写MCP Bearer令牌。
- 破坏性工具需要`confirm: true`。
- 所有工具调用都有限速。破坏性工具有更严格的默认限制。
- 默认情况下，审计条目写入`data/audit.jsonl`。
- 设置`AUDIT_MAX_ENTRIES`或`audit.maxEntries`以修剪较旧的记录并仅保留最新的记录。
- API响应和错误被净化以去除Bearer令牌、密码、堆栈跟踪、共享密钥、DNSSEC私钥和敏感的本地路径。
## 配置
必需：
- `MCP_READ_BEARER_TOKENS`或`MCP_READWRITE_BEARER_TOKENS`
- `TECHNITIUM_BASE_URL`
- `TECHNITIUM_API_TOKEN`或`TECHNITIUM_API_TOKEN_FILE`
Bearer令牌变量是JSON5数组：
```json5
[{ name: "reader1", token: "replace-me" }]
```
也支持令牌文件：
```json5
[{ name: "reader1", tokenFile: "./data/mcp-reader.token" }]
```
复制`.env.example`到`.env`用于基于环境的本地开发，或复制`config.example.json5`到`data/config.json5`用于基于文件的配置。环境变量覆盖`data/config.json5`。`BACKUP_DIR`存储由`dns_backup_settings`创建的ZIP文件；`IMPORT_DIR`是ZIP文件必须放置在`dns_restore_settings`或`dns_update_app`可以读取它们之前的位置。
设置`AUDIT_RECORD_READS=true`或`audit.recordReads: true`以将只读MCP调用追加到审计文件进行故障排除。审计条目存储请求元数据、身份名称、工具名称、已净化参数、结果计数（如果可用）和错误代码（如果工具返回错误）；它们不存储未净化的Technitium响应正文。
如果启用HTTPS且`server.crt`/`server.key`在`CERTS_DIR`中丢失，则服务器生成本地自签名证书。
<details>
<summary>常见的可选变量</summary>
```env
CONFIG_FILE=./data/config.json5
HTTPS_ENABLED=true
HTTPS_HOST=0.0.0.0
HTTPS_PORT=3443
HTTP_ENABLED=false
HTTP_HOST=0.0.0.0
HTTP_PORT=3000
READ_ONLY=false
TECHNITIUM_TIMEOUT_MS=10000
TECHNITIUM_TLS_REJECT_UNAUTHORIZED=true
TECHNITIUM_ALLOW_HTTP_LOCAL=false
TECHNITIUM_ALLOW_HTTP_HOSTNAMES=
READY_CHECK_TECHNITIUM=false
AUTH_HEALTHCHECKS=false
AUDIT_ENABLED=true
AUDIT_FILE=./data/audit.jsonl
AUDIT_RECORD_READS=false
AUDIT_MAX_ENTRIES=0
BACKUP_DIR=./data/backups
IMPORT_DIR=./data/imports
CERTS_DIR=./data/certs
INCLUDE_RAW_DEFAULT=false
RATE_LIMIT_READ_MAX=120
RATE_LIMIT_READ_WINDOW_MS=60000
RATE_LIMIT_WRITE_MAX=30
RATE_LIMIT_WRITE_WINDOW_MS=60000
RATE_LIMIT_DESTRUCTIVE_MAX=5
RATE_LIMIT_DESTRUCTIVE_WINDOW_MS=60000
```
</details>
## Docker
构建并运行本地镜像：
```bash
mkdir -p data
printf '%s\n' 'replace-technitium-api-token' > data/technitium-api.token
docker build -t mcp-technitium-dns:local .
docker run --rm \
-p 3443:3443 \
-v "$PWD/data:/app/data" \
-e MCP_READ_BEARER_TOKENS='[{name:"reader1",token:"read-token"}]' \
-e MCP_READWRITE_BEARER_TOKENS='[{name:"admin1",token:"write-token"}]' \
-e TECHNITIUM_BASE_URL='https://technitium.lan:53443' \
-e TECHNITIUM_API_TOKEN_FILE='./data/technitium-api.token' \
mcp-technitium-dns:local
```
## Kubernetes
<details>
<summary>Kubernetes 清单</summary>
```yml
apiVersion: v1
kind: Secret
metadata:
name: technitium-dns-mcp
type: Opaque
stringData:
MCP_READ_BEARER_TOKENS: '[{name:"reader1",token:"read-token"}]'
MCP_READWRITE_BEARER_TOKENS: '[{name:"admin1",token:"write-token"}]'
TECHNITIUM_BASE_URL: 'https://technitium.lan:53443'
TECHNITIUM_API_TOKEN: 'replace-me'
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: technitium-dns-mcp
spec:
replicas: 1
selector:
matchLabels:
app: technitium-dns-mcp
template:
metadata:
labels:
app: technitium-dns-mcp
spec:
containers:
- name: server
image: slyke/mcp-technitium-dns:latest
ports:
- containerPort: 3443
envFrom:
- secretRef:
name: technitium-dns-mcp
env:
- name: HTTPS_ENABLED
value: "true"
- name: HTTP_ENABLED
value: "false"
- name: READY_CHECK_TECHNITIUM
value: "false"
readinessProbe:
httpGet:
path: /readyz
port: 3443
scheme: HTTPS
livenessProbe:
httpGet:
path: /healthz
port: 3443
scheme: HTTPS
```
</details>
## Codex MCP 配置
<details>
<summary>完整的 Codex MCP 配置</summary>
```toml
[mcp_servers.technitium_dns]
url = "https://technitium-dns-mcp.lan:3443/mcp"
bearer_token_env_var = "TECHNITIUM_DNS_MCP_TOKEN"
default_tools_approval_mode = "prompt"
[mcp_servers.technitium_dns.tools.dns_health_check]
approval_mode = "auto"
[mcp_servers.technitium_dns.tools.dns_get_stats]
approval_mode = "auto"
[mcp_servers.technitium_dns.tools.dns_list_zones]
approval_mode = "auto"
[mcp_servers.technitium_dns.tools.dns_list_records]
approval_mode = "auto"
[mcp_servers.technitium_dns.tools.dns_zone_options]
approval_mode = "auto"
[mcp_servers.technitium_dns.tools.dns_resolve]
approval_mode = "auto"
[mcp_servers.technitium_dns.tools.dns_get_settings]
approval_mode = "auto"
[mcp_servers.technitium_dns.tools.dns_query_logs]
approval_mode = "auto"
[mcp_servers.technitium_dns.tools.dns_audit_search]
approval_mode = "auto"
[mcp_servers.technitium_dns.tools.dns_whoami]
approval_mode = "auto"
[mcp_servers.technitium_dns.tools.dns_create_zone]
approval_mode = "prompt"
[mcp_servers.technitium_dns.tools.dns_delete_zone]
approval_mode = "prompt"
[mcp_servers.technitium_dns.tools.dns_add_record]
approval_mode = "prompt"
[mcp_servers.technitium_dns.tools.dns_update_record]
approval_mode = "prompt"
[mcp_servers.technitium_dns.tools.dns_delete_record]
approval_mode = "prompt"
[mcp_servers.technitium_dns.tools.dns_set_settings]
approval_mode = "prompt"
[mcp_servers.technitium_dns.tools.dns_flush_cache]
approval_mode = "prompt"
[mcp_servers.technitium_dns.tools.dns_backup_settings]
approval_mode = "prompt"
[mcp_servers.technitium_dns.tools.dns_restore_settings]
approval_mode = "prompt"
```
</details>
<details>
<summary>WSL2 环境变量故障排除</summary>
Codex 在 MCP 服务器初始化时从 Codex 主机环境中解析 `bearer_token_env_var`。如果 Technitium MCP 工具未出现，请首先验证新的 WSL2 启动是否可以在不打印令牌的情况下看到令牌：
```powershell
wsl.exe -d Ubuntu -- bash -lc '[ -n "$TECHNITIUM_DNS_MCP_TOKEN" ] && echo technitium=set || echo technitium=missing'
```
如果报告为 `missing`，但已打开的 WSL shell 报告为 `set`，则令牌仅在该交互式 shell 中可用。对于 Windows 上的 Codex Desktop，请在 Windows 用户环境中设置令牌，并将其转发到 WSL：
```powershell
[Environment]::SetEnvironmentVariable("TECHNITIUM_DNS_MCP_TOKEN", "replace-read-or-readwrite-token", "User")
$current = [Environment]::GetEnvironmentVariable("WSLENV", "User")
$entries = @("TECHNITIUM_DNS_MCP_TOKEN/u")
$merged = (@($current -split ":" | Where-Object { $_ }) + $entries | Select-Object -Unique) -join ":"
[Environment]::SetEnvironmentVariable("WSLENV", $merged, "User")
```
在更改用户环境变量后重启 Codex Desktop，然后启动新任务。通常，现有的任务无法获得新初始化的 MCP 工具。
如果您在 WSL 内运行 Codex CLI，只需在启动 Codex 之前导出令牌即可：
```bash
export TECHNITIUM_DNS_MCP_TOKEN="replace-read-or-readwrite-token"
codex
```
如果令牌可见但工具仍然无法加载，请分别检查 MCP URL、DNS 解析和 TLS 信任。对于私有证书颁发机构，请通过 `CODEX_CA_CERTIFICATE` 或 `SSL_CERT_FILE` 将 Codex 配置为使用受信任的 PEM 捆绑包。
</details>
## 工具
只读工具：
- `dns_health_check`
- `dns_get_stats`
- `dns_check_update`
- `dns_resolve`
- `dns_list_zones`
- `dns_zone_options`
- `dns_export_zone`
- `dns_list_records`
- `dns_list_blocked`
- `dns_list_allowed`
- `dns_list_cache`
- `dns_get_settings`
- `dns_query_logs`
- `dns_list_apps`
- `dns_list_app_store`
- `dns_get_app_config`
- `dns_dnssec_info`
- `dns_get_ds`
- `dns_audit_list`
- `dns_audit_search`
- `dns_audit_read`
- `dns_whoami`
- `dns_metrics_prometheus`
- `dns_list_sessions`
- `dns_list_tsig_keys`
- `dns_list_log_files`
- `dns_read_log_file`
- `dns_export_query_logs`
- `dns_dhcp_list_leases`
- `dns_dhcp_list_scopes`
- `dns_dhcp_get_scope`
写入工具：
- `dns_create_zone`
- `dns_delete_zone`
- `dns_enable_zone`
- `dns_disable_zone`
- `dns_set_zone_options`
- `dns_add_record`
- `dns_update_record`
- `dns_delete_record`
- `dns_block_domain`
- `dns_remove_blocked`
- `dns_flush_blocked`
- `dns_allow_domain`
- `dns_remove_allowed`
- `dns_flush_allowed`
- `dns_flush_cache`
- `dns_delete_cached`
- `dns_set_settings`
- `dns_update_blocklists`
- `dns_temp_disable_blocking`
- `dns_install_app`
- `dns_uninstall_app`
- `dns_delete_session`
- `dns_dnssec_sign`
- `dns_dnssec_unsign`
- `dns_dnssec_rollover_key`
- `dns_backup_settings`
- `dns_restore_settings`
- `dns_download_update_app`
- `dns_update_app`
- `dns_set_app_config`
- `dns_delete_log_file`
- `dns_delete_all_logs`
- `dns_dhcp_remove_lease`
- `dns_dhcp_convert_lease_reserved`
- `dns_dhcp_convert_lease_dynamic`
- `dns_dhcp_set_scope`
- `dns_dhcp_add_reserved_lease`
- `dns_dhcp_remove_reserved_lease`
- `dns_dhcp_enable_scope`
- `dns_dhcp_disable_scope`
- `dns_dhcp_delete_scope`
`READ_ONLY=true`在注册时省略所有写入工具。破坏性写入工具需要`confirm: true`；这些工具包括删除区域/记录/会话/日志/DHCP作用域、刷新缓存/允许/阻止列表、卸载应用程序、恢复设置、取消签名或滚动DNSSEC密钥以及删除DHCP租约。
## CLI MCP 客户端
此服务器在 `/mcp` 上公开可流式传输的 HTTP MCP。启动服务器后，将 CLI 客户端指向 `https://<host>:3443/mcp` 并使用已配置的 MCP Bearer 令牌之一。
### Claude 代码
对于单机设置，请添加带有授权头的远程 HTTP 服务器：
```bash
export TECHNITIUM_DNS_MCP_TOKEN="replace-read-or-readwrite-token"
claude mcp add --transport http technitium-dns https://technitium-dns-mcp.lan:3443/mcp \
--header "Authorization: Bearer ${TECHNITIUM_DNS_MCP_TOKEN}"
claude
```
对于可共享的项目配置，请创建 `.mcp.json` 并在环境中保留令牌：
```json
{
"mcpServers": {
"technitium-dns": {
"type": "http",
"url": "https://technitium-dns-mcp.lan:3443/mcp",
"headers": {
"Authorization": "Bearer ${TECHNITIUM_DNS_MCP_TOKEN}"
}
}
}
}
```
运行 `TECHNITIUM_DNS_MCP_TOKEN="replace-read-or-readwrite-token" claude`，然后在 Claude Code 中使用 `/mcp` 确认服务器已连接。
### Codex CLI
Codex CLI 为流式 HTTP MCP 服务器使用 `config.toml`。将以下内容添加到 `~/.codex/config.toml` 或受信任项目中的 `.codex/config.toml`：
```toml
[mcp_servers.technitium_dns]
url = "https://technitium-dns-mcp.lan:3443/mcp"
bearer_token_env_var = "TECHNITIUM_DNS_MCP_TOKEN"
default_tools_approval_mode = "prompt"
```
然后运行：
```bash
export TECHNITIUM_DNS_MCP_TOKEN="replace-read-or-readwrite-token"
codex
```
在 Codex TUI 中使用 `/mcp` 确认服务器已连接。`codex mcp add` 适用于stdio MCP服务器；对于此HTTP服务器，请使用上面的TOML表单。
## 开发
```bash
npm install
npm test
mkdir -p data/certs data/backups data/imports
cp config.example.json5 data/config.json5
node src/index.js
```
健康端点返回：
```json
{
"ok": true,
"version": "0.1.0",
"buildHash": "unknown",
"readOnly": false
}
```
## 镜像发布
参见 [IMAGE_PUBLISHING.md](./IMAGE_PUBLISHING.md) 获取版本镜像标签和发布工作流程。
## 许可证
在 MIT 许可证下发布。参见 [LICENSE.md](./LICENSE.md)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器