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 update
dns_temp_disable_blocking	Temporarily disable blocking (auto re-enables)
dns_install_app	Install a DNS app from the app store
dns_uninstall_app	Uninstall an app (requires confirm: true)

Security

Generating an API Token

An API token is the recommended way to authenticate. Tokens avoid sending your admin password on every request and can be revoked independently.

Option A: Web Admin UI

1. Open the Technitium web admin (e.g. http://your-server-ip:5380)
2. Log in with your admin credentials
3. Go to Administration (gear icon, top right)
4. Scroll down to Sessions
5. Under Create API Token, enter a name (e.g. mcp-server)
6. Click Create
7. Copy the token value shown - this is the only time it will be displayed

Option B: API (curl)

# Login first to get a session token
curl -s -X POST 'http://your-server-ip:5380/api/user/login' \
  -d 'user=admin&pass=yourpassword' | jq -r '.response.token'

# Then create a non-expiring API token using the session token
curl -s -X POST 'http://your-server-ip:5380/api/user/createToken' \
  -d 'user=admin&pass=yourpassword&tokenName=mcp-server' | jq -r '.response.token'

Storing the token securely:

# Option 1: Pass directly as env var (simplest)
claude mcp add technitium-dns \
  --env TECHNITIUM_TOKEN=your-token-here ...

# Option 2: Use a token file (more secure - keeps token out of shell history)
echo "your-token-here" > ~/.technitium-token
chmod 600 ~/.technitium-token

claude mcp add technitium-dns \
  --env TECHNITIUM_TOKEN_FILE=~/.technitium-token ...

Local Network (HTTP)

If your Technitium server doesn't have TLS configured (common for LAN-only setups), you need to explicitly allow HTTP:

claude mcp add technitium-dns \
  --env TECHNITIUM_URL=http://your-server-ip:5380 \
  --env TECHNITIUM_TOKEN=your-token \
  --env TECHNITIUM_ALLOW_HTTP=true \
  -- node /path/to/technitium-mcp-secure/dist/index.js

A warning will be logged to stderr reminding you that credentials are sent in plaintext.

Read-only Mode

For monitoring-only use cases, hide all write tools:

claude mcp add technitium-dns-readonly \
  --env TECHNITIUM_URL=http://your-server-ip:5380 \
  --env TECHNITIUM_TOKEN=your-token \
  --env TECHNITIUM_READONLY=true \
  --env TECHNITIUM_ALLOW_HTTP=true \
  -- node /path/to/dist/index.js

Rate Limits

• Global: 100 requests/minute
• Create/mutate operations: 10/minute
• Delete/flush operations: 5/minute

Audit Log

All tool calls are logged as JSONL to stderr with timestamps, tool name, sanitized arguments, result status, and duration. Sensitive values (tokens, passwords) are redacted before logging.

Not Yet Implemented

The Technitium API has ~173 endpoints. This MCP server covers the most useful 36. The following categories are available in the API but not yet exposed:

• DHCP management — scopes, leases, reservations (~12 endpoints)
• User & group administration — create/delete users, manage groups, permissions (~15 endpoints)
• Cluster management — multi-server clustering, health, failover (~15 endpoints)
• Zone import/clone/convert — import from file, clone from another server, convert zone types
• DNSSEC signing & key management — sign/unsign zones, rotate keys, algorithm config
• Allowed/blocked zone import/export — bulk import/export from files
• Settings backup/restore — full server config backup and restore
• Log management — log file deletion, log settings changes

If you need any of these, contributions are welcome or open an issue.

Compatibility

Tested against Technitium DNS Server v14.3 on Alpine Linux. All 36 API endpoints verified against the live v14 API.

Note: Technitium's API paths changed between versions. If you see 404 errors, check that your server version is v14+. Earlier versions used different paths (e.g. /api/allowedZones/list instead of /api/allowed/list).

Requirements

• Node.js >= 18
• Technitium DNS Server v14+

Changelog

v1.2.0

• Add 19 new tools (39 total): remove/flush allowed & blocked, delete cached, enable/disable/configure/export zones, server settings management, temporary blocking disable, block list updates, app store/install/uninstall/config, DNSSEC info, update check
• All 36 API endpoints verified returning 200 against live Technitium v14.3
• Add "Not Yet Implemented" section documenting available API categories

v1.1.1

• Fix dns_resolve missing required server parameter (now defaults to this-server)
• Fix dns_query_logs missing name and classPath params for Query Logs (Sqlite) app
• Fix dns_list_allowed, dns_allow_domain using wrong API path (/api/allowedZones/* -> /api/allowed/*)
• Fix dns_list_blocked, dns_block_domain using wrong API path (/api/blockedZones/* -> /api/blocked/*)
• Fix dns_list_cache using wrong API path (/api/cache/zones/list -> /api/cache/list)
• Fix dns_allow_domain, dns_block_domain using wrong param name (zone -> domain)
• All 17 API endpoints verified returning 200 against live Technitium v14.3

v1.1.0

• Security hardening: input validation, audit logging, rate limiting, response sanitization
• HTTPS enforcement with HTTP opt-in, read-only mode, confirmation for destructive ops
• Token file support, auth mutex, POST-only API calls, env var clearing

v1.0.0

• Initial release with 20 tools for DNS management

License

MIT