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:

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)

Write (21 tools)

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