README.md
technitium-mcp-secure
A security-hardened Model Context Protocol (MCP) server for managing Technitium DNS Server via its HTTP API.
Built for use with Claude Code and other MCP-compatible clients.
Features
- 39 tools covering DNS zones, records, blocking, cache, settings, apps, DNSSEC, logs, and diagnostics
- Input validation on all parameters (RFC 1035 domain checks, IP validation, enum allowlists)
- HTTPS enforcement with explicit HTTP opt-in for local networks
- Read-only mode to expose only safe query tools
- Confirmation required for destructive operations (delete zone, delete record, flush cache/allow/block, uninstall app)
- Rate limiting with stricter limits on destructive operations
- Audit logging as structured JSONL to stderr
- Response sanitization to strip tokens, passwords, stack traces, and sensitive paths
- Error sanitization to prevent credential/path leakage in error messages
- Token file support for secure credential storage
- Auth mutex to prevent concurrent authentication races
- POST-only API calls for all mutating operations; zone export uses GET (required by Technitium API) with short-lived session tokens
Quick Start
# Clone and build
git clone https://github.com/rosschurchill/technitium-mcp-secure.git
cd technitium-mcp-secure
npm install
npm run build
# Register with Claude Code (see "Generating an API Token" below first)
claude mcp add technitium-dns \
--env TECHNITIUM_URL=https://your-server-ip:5380 \
--env TECHNITIUM_TOKEN=your-api-token \
-- node /path/to/technitium-mcp-secure/dist/index.js
Configuration
All configuration is via environment variables:
| Variable | Required | Description |
|---|---|---|
TECHNITIUM_URL |
Yes | Server URL (e.g. https://192.168.1.100:5380) |
TECHNITIUM_TOKEN |
One of token/password | API token (preferred) |
TECHNITIUM_TOKEN_FILE |
One of token/password | Path to file containing token (must be mode 0600) |
TECHNITIUM_PASSWORD |
One of token/password | Admin password (token is preferred) |
TECHNITIUM_USER |
No | Username (default: admin) |
TECHNITIUM_READONLY |
No | Set true to hide all write tools |
TECHNITIUM_ALLOW_HTTP |
No | Set true to allow insecure HTTP connections |
Authentication priority: TECHNITIUM_TOKEN > TECHNITIUM_TOKEN_FILE > TECHNITIUM_PASSWORD
Sensitive environment variables are cleared from process.env after being read.
Tools
Read-only (18 tools)
| Tool | Description |
|---|---|
dns_health_check |
Server version, uptime, forwarder config, failure rate |
dns_get_stats |
Query statistics with top clients/domains/blocked |
dns_check_update |
Check if a newer server version is available |
dns_resolve |
Test DNS resolution via the server |
dns_list_zones |
List all configured zones |
dns_zone_options |
Zone DNSSEC, transfer, and notify settings |
dns_export_zone |
Export a zone file in BIND format |
dns_list_records |
List records in a zone |
dns_list_blocked |
List blocked domains (hierarchical, supports drill-down) |
dns_list_allowed |
List allowed domains (hierarchical, supports drill-down) |
dns_list_cache |
List cached zones (hierarchical, supports drill-down) |
dns_get_settings |
Full server settings |
dns_query_logs |
Query DNS logs with filters |
dns_list_apps |
List installed DNS apps |
dns_list_app_store |
List available apps from the Technitium app store |
dns_get_app_config |
Get configuration for an installed app |
dns_dnssec_info |
DNSSEC properties for a zone |
dns_get_ds |
DS records for a DNSSEC-signed zone |
Write (21 tools)
| Tool | Description |
|---|---|
dns_create_zone |
Create a new DNS zone |
dns_delete_zone |
Delete a zone (requires confirm: true) |
dns_enable_zone |
Enable a disabled zone |
dns_disable_zone |
Disable a zone (preserves records) |
dns_set_zone_options |
Update zone configuration (notify, transfer ACLs) |
dns_add_record |
Add a DNS record |
dns_update_record |
Update an existing record |
dns_delete_record |
Delete a record (requires confirm: true) |
dns_block_domain |
Block a domain |
dns_remove_blocked |
Remove a domain from the block list |
dns_flush_blocked |
Flush entire custom block list (requires confirm: true) |
dns_allow_domain |
Allow a domain (bypass block lists) |
dns_remove_allowed |
Remove a domain from the allow list |
dns_flush_allowed |
Flush entire allow list (requires confirm: true) |
dns_flush_cache |
Flush DNS cache (requires confirm: true) |
dns_delete_cached |
Delete a specific domain from cache |
dns_set_settings |
Update server settings (forwarders, blocking, etc.) |
dns_update_blocklists |
Force immediate block list |
Tools 7
dns_health_checkGet server version, uptime, forwarder config, and failure rate.dns_get_statsGet query statistics with top clients, domains, and blocked requests.dns_list_zonesList all configured DNS zones.dns_list_recordsList records in a specific zone.dns_add_recordAdd a new DNS record to a zone.dns_block_domainBlock a specific domain.dns_flush_cacheFlush the DNS cache.Environment Variables
TECHNITIUM_URLrequiredServer URL (e.g. https://192.168.1.100:5380)TECHNITIUM_TOKENAPI token for authenticationTECHNITIUM_TOKEN_FILEPath to file containing tokenTECHNITIUM_PASSWORDAdmin passwordTECHNITIUM_READONLYSet true to hide all write toolsTry it
→Check the current health and uptime of my Technitium DNS server.
→List all the DNS zones currently configured on the server.
→Add a new A record for 'test.example.com' pointing to 192.168.1.50.
→Show me the top blocked domains from the DNS statistics.
→Flush the DNS cache to ensure all records are updated.