Content
# mcp-technitium-dns
Safety-focused MCP server for querying and managing Technitium DNS Server through the Technitium HTTP API. Codex or other MCP clients authenticate to this server with named Bearer tokens; this server authenticates to Technitium with a Technitium API token in the `Authorization: Bearer ...` header. Technitium credentials are never exposed to MCP clients.
Record tools use strict, validated snake_case inputs and map them to Technitium API parameters. For example, an A record uses `record: { ip_address: "192.0.2.10", ttl: 3600 }`; an MX record uses `record: { preference: 10, exchange: "mail.example.com" }`.
Zone export uses Technitium's required GET endpoint with a single-use API token created immediately before export.
`READ_ONLY=true` registers only read-only tools. Write tools require a readwrite MCP bearer token, and destructive tools require `confirm: true`.
## Technitium Setup
Target: Technitium DNS Server with API-token based automation.
- Use HTTPS for Technitium whenever possible.
- If Technitium is only available over HTTP, set `TECHNITIUM_ALLOW_HTTP_LOCAL=true`; the target host must still be local/private unless it is explicitly listed in `TECHNITIUM_ALLOW_HTTP_HOSTNAMES`.
- Create a dedicated Technitium user for MCP automation.
- Grant only the permissions needed for your intended tools.
- Store the Technitium API token in a protected file and use `TECHNITIUM_API_TOKEN_FILE` for production deployments.
- Set `READ_ONLY=true` when the server should expose only read-only MCP tools.
## Creating a Technitium API Token
1. Log in to the Technitium DNS web console as an administrator.
2. Create a dedicated user for MCP automation, or use an existing dedicated automation user.
3. Grant only the permissions needed for your intended tools. Read-only use needs view permissions for Dashboard, Zones, Cache, Allowed, Blocked, Apps, DNS Client, Settings, Administration, DHCP Server, and Logs. Write use needs modify/delete permissions for the sections you intend to manage.
4. Open the user menu/profile for that account and create an API token with a clear token name, for example `mcp-technitium-dns`.
5. Copy the generated token immediately.
6. Store it in a protected file and configure `TECHNITIUM_API_TOKEN_FILE`, or set `TECHNITIUM_API_TOKEN` for local testing.
The API token is passed to Technitium as `Authorization: Bearer <token>`. Do not configure your Technitium username/password in this MCP server.
## Safety Model
- HTTPS is the default for this MCP server.
- Technitium `TECHNITIUM_BASE_URL` must use HTTPS unless `TECHNITIUM_ALLOW_HTTP_LOCAL=true` and the target host is local/private.
- Write tools require a readwrite MCP bearer token.
- Destructive tools require `confirm: true`.
- All tool calls are rate-limited. Destructive tools have a stricter default limit.
- Audit entries are written to `data/audit.jsonl` by default.
- Set `AUDIT_MAX_ENTRIES` or `audit.maxEntries` to prune older records and keep only the newest entries.
- API responses and errors are sanitized to strip bearer tokens, passwords, stack traces, shared secrets, DNSSEC private keys, and sensitive local paths.
## Configuration
Required:
- `MCP_READ_BEARER_TOKENS` or `MCP_READWRITE_BEARER_TOKENS`
- `TECHNITIUM_BASE_URL`
- `TECHNITIUM_API_TOKEN` or `TECHNITIUM_API_TOKEN_FILE`
Bearer token variables are JSON5 arrays:
```json5
[{ name: "reader1", token: "replace-me" }]
```
Token files are also supported:
```json5
[{ name: "reader1", tokenFile: "./data/mcp-reader.token" }]
```
Copy `.env.example` to `.env` for environment-based local development, or copy `config.example.json5` to `data/config.json5` for file-based configuration. Environment variables override `data/config.json5`. `BACKUP_DIR` stores ZIP files created by `dns_backup_settings`; `IMPORT_DIR` is where ZIP files must be placed before `dns_restore_settings` or `dns_update_app` can read them.
Set `AUDIT_RECORD_READS=true` or `audit.recordReads: true` to append read-only MCP calls to the audit file for troubleshooting. Audit entries store request metadata, identity name, tool name, redacted arguments, result count when available, and error code when a tool returns an error; they do not store unsanitized Technitium response bodies.
If HTTPS is enabled and `server.crt`/`server.key` are missing in `CERTS_DIR`, the server generates a local self-signed certificate.
<details>
<summary>Common optional variables</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
Build and run a local image:
```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 manifest</summary>
```yaml
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 Config
<details>
<summary>Full Codex MCP config</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 environment variable troubleshooting</summary>
Codex resolves `bearer_token_env_var` from the Codex host environment when the MCP server initializes. If the Technitium MCP tools do not appear, first verify that a fresh WSL2 launch can see the token without printing it:
```powershell
wsl.exe -d Ubuntu -- bash -lc '[ -n "$TECHNITIUM_DNS_MCP_TOKEN" ] && echo technitium=set || echo technitium=missing'
```
If that reports `missing`, but an already-open WSL shell reports `set`, the token is only available in that interactive shell. For Codex Desktop on Windows, set the token in the Windows user environment and forward it into 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")
```
Restart Codex Desktop after changing user environment variables, then start a new task. Existing tasks usually will not gain newly initialized MCP tools.
If you run Codex CLI from inside WSL instead, exporting the token before launching Codex is enough:
```bash
export TECHNITIUM_DNS_MCP_TOKEN="replace-read-or-readwrite-token"
codex
```
If the token is visible but the tools still do not load, check the MCP URL, DNS resolution, and TLS trust separately. For private certificate authorities, configure Codex with a trusted PEM bundle through `CODEX_CA_CERTIFICATE` or `SSL_CERT_FILE`.
</details>
## Tools
Read-only tools:
- `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`
Write tools:
- `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` omits all write tools at registration time. Destructive write tools require `confirm: true`; these include deleting zones/records/sessions/logs/DHCP scopes, flushing cache/allow/block lists, uninstalling apps, restoring settings, unsigning or rolling DNSSEC keys, and removing DHCP leases.
## CLI MCP Clients
This server exposes Streamable HTTP MCP at `/mcp`. Start the server first, then point CLI clients at `https://<host>:3443/mcp` and use one of the configured MCP bearer tokens.
### Claude Code
For a one-machine setup, add the remote HTTP server with an Authorization header:
```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
```
For a project-shareable config, create `.mcp.json` and keep the token in the environment:
```json
{
"mcpServers": {
"technitium-dns": {
"type": "http",
"url": "https://technitium-dns-mcp.lan:3443/mcp",
"headers": {
"Authorization": "Bearer ${TECHNITIUM_DNS_MCP_TOKEN}"
}
}
}
}
```
Run `TECHNITIUM_DNS_MCP_TOKEN="replace-read-or-readwrite-token" claude`, then use `/mcp` inside Claude Code to confirm the server is connected.
### Codex CLI
Codex CLI uses `config.toml` for Streamable HTTP MCP servers. Add this to `~/.codex/config.toml`, or to `.codex/config.toml` in a trusted project:
```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"
```
Then run:
```bash
export TECHNITIUM_DNS_MCP_TOKEN="replace-read-or-readwrite-token"
codex
```
Use `/mcp` in the Codex TUI to confirm the server is connected. `codex mcp add` is useful for stdio MCP servers; for this HTTP server, use the TOML form above.
## Development
```bash
npm install
npm test
mkdir -p data/certs data/backups data/imports
cp config.example.json5 data/config.json5
node src/index.js
```
Health endpoints return:
```json
{
"ok": true,
"version": "0.1.0",
"buildHash": "unknown",
"readOnly": false
}
```
## Image Publishing
See [IMAGE_PUBLISHING.md](./IMAGE_PUBLISHING.md) for the versioned image tagging and publishing workflow.
## License
Released under the MIT License. See [LICENSE.md](./LICENSE.md).
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available