Skip to main content
Glama
technitium-mcp-secure

technitium-mcp-secure

by nomi25home

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

Related MCP server: @kodim/mcp-cloudflare-dns

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

Available Tools

39 tools
dns_add_recordA

Add a DNS record to a zone. Creates the zone automatically if it doesn't exist for Primary type.

Inputs: type (required), zone (required), value (required), domain (required), +3 more.

dns_allow_domainA

Allow a domain name, bypassing any block lists. Useful for whitelisting false positives.

Inputs: domain (required).

dns_block_domainA

Block a domain name. Queries to this domain will be denied by the DNS server.

Inputs: domain (required).

dns_check_updateA

Check if a newer version of Technitium DNS Server is available.

Inputs: no named parameters.

dns_create_zoneA

Create a new DNS zone. Use 'Primary' for hosting records locally, 'Forwarder' for conditional forwarding.

Inputs: zone (required), type.

dns_delete_cachedA

Delete a specific domain from the DNS cache. Unlike flush, this only removes the specified domain.

Inputs: domain (required).

dns_delete_recordA

Delete a specific DNS record from a zone. Requires confirm=true to execute.

Inputs: type (required), zone (required), value (required), domain (required), +1 more.

dns_delete_zoneA

Delete a DNS zone and all its records. Requires confirm=true to execute.

Inputs: zone (required), confirm.

dns_disable_zoneA

Disable a DNS zone. The zone will stop responding to queries but its records are preserved.

Inputs: zone (required).

dns_dnssec_infoB

Get DNSSEC properties for a zone including signing status, key details, and algorithm info.

Inputs: zone (required).

dns_enable_zoneB

Enable a disabled DNS zone.

Inputs: zone (required).

dns_export_zoneA

Export a DNS zone file in standard BIND format. Returns the zone file as text.

Inputs: zone (required).

dns_flush_allowedA

Flush the entire allow list. All allowed domains will be removed. Requires confirm=true to execute.

Inputs: confirm.

dns_flush_blockedA

Flush the entire custom block list. All manually blocked domains will be removed. Requires confirm=true to execute.

Inputs: confirm.

dns_flush_cacheA

Flush the entire DNS cache. Forces all subsequent queries to be resolved fresh from upstream. Requires confirm=true to execute.

Inputs: confirm.

dns_get_app_configB

Get the configuration for an installed DNS app.

Inputs: name (required).

dns_get_dsA

Get the DS (Delegation Signer) records for a DNSSEC-signed zone. These are needed by the parent zone registrar.

Inputs: zone (required).

dns_get_settingsA

Get the current DNS server settings including forwarders, blocking configuration, protocols, logging, cache settings, and proxy configuration.

Inputs: no named parameters.

dns_get_statsA

Get DNS query statistics for a time period. Returns total queries, cached, blocked, failure counts, plus top clients, top domains, and top blocked domains.

Inputs: period.

dns_health_checkA

Quick health check of the DNS server. Returns version, uptime, forwarder config, blocking status, and last hour failure rate.

Inputs: no named parameters.

dns_install_appA

Download and install a DNS app from the Technitium app store. Use dns_list_app_store to see available apps.

Inputs: name (required).

dns_list_allowedA

List allowed DNS zones (domains that bypass block lists). Returns a hierarchical tree — call with no domain to see top-level zones, then pass a domain (e.g. 'com') to drill into subdomains.

Inputs: domain.

dns_list_appsA

List installed DNS apps on the server and their current status.

Inputs: no named parameters.

dns_list_app_storeA

List all available apps from the Technitium DNS app store with versions and descriptions.

Inputs: no named parameters.

dns_list_blockedA

List blocked DNS zones (domains that are denied). Returns a hierarchical tree — call with no domain to see top-level zones, then pass a domain (e.g. 'com') to drill into subdomains.

Inputs: domain.

dns_list_cacheA

List zones in the DNS cache. Returns a hierarchical tree — call with no domain to see top-level zones, then pass a domain (e.g. 'com') to drill into cached subdomains.

Inputs: domain.

dns_list_recordsA

List DNS records in a zone. Optionally filter by a specific domain name within the zone. When no domain is specified, returns all records across all zones matching the zone name (including subzones like app.example.com when zone=example.com). When domain is specified, returns records for that exact domain only.

Inputs: zone (required), domain.

dns_list_zonesA

List all DNS zones configured on the server. Returns zone name, type (Primary/Secondary/Stub/Forwarder), status, and record count.

Inputs: no named parameters.

dns_query_logsA

Query DNS server logs with optional filters. Returns recent DNS queries and their responses. Requires the Query Logs app to be installed.

Inputs: domain, clientIp, queryType, pageNumber, +2 more.

dns_remove_allowedA

Remove a domain from the allow list. The domain will no longer bypass block lists.

Inputs: domain (required).

dns_remove_blockedB

Remove a domain from the block list. The domain will no longer be denied.

Inputs: domain (required).

dns_resolveA

Test DNS resolution for a domain name. Resolves using the Technitium server itself or a specified external server.

Inputs: domain (required), type, server, protocol.

dns_set_settingsA

Update DNS server settings. Pass key/value pairs for any settings to change (e.g. forwarders, blocking, recursion, cache). Use dns_get_settings first to see current values and available keys.

Inputs: forwarders, logQueries, preferIPv6, blockListUrls, +4 more.

dns_set_zone_optionsA

Set configuration options for a zone. Pass the zone name plus any option key/value pairs to update (e.g. notify settings, zone transfer ACLs).

Inputs: zone (required), disabled, notifyNameServers, zoneTransferAllowedNetworks.

dns_temp_disable_blockingA

Temporarily disable domain blocking for a specified number of minutes. Blocking re-enables automatically after the timer expires.

Inputs: minutes.

dns_uninstall_appA

Uninstall a DNS app from the server. Requires confirm=true to execute.

Inputs: name (required), confirm.

dns_update_blocklistsA

Force an immediate update of all configured block lists. Normally block lists update every 24 hours.

Inputs: no named parameters.

dns_update_recordC

Update an existing DNS record.

Inputs: type (required), zone (required), value (required), domain (required), +3 more.

dns_zone_optionsA

Get the configuration options for a specific zone including DNSSEC, transfer, and notify settings.

Inputs: zone (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 39 tools

    Disambiguation5/5

    Each tool names a distinct resource and action: zones, records, cache, block lists, allow lists, apps, settings, and DNSSEC are cleanly separated. Even similar-looking tools like dns_remove_blocked and dns_flush_blocked differ clearly by single-item versus full-list scope.

    Naming Consistency4/5

    The dns_ prefix plus verb_noun pattern is used consistently across nearly all tools, e.g. dns_list_zones, dns_create_zone, dns_delete_record, dns_install_app. A few names break the get_ convention, notably dns_zone_options and dns_dnssec_info, which keeps this from a perfect score.

    Tool Count2/5

    39 tools is well beyond the ideal 3-15 range and even beyond the 16-25 heavy range. While the Technitium DNS surface is broad, several clusters like block lists, allow lists, cache, and zones could be consolidated into parameterized list/update tools without losing capability.

    Completeness4/5

    The toolset covers the core DNS lifecycle: zone and record CRUD, cache management, blocking/allowlisting, server settings, apps, logs, stats, and DNSSEC info. Minor gaps such as missing zone import and no explicit DNSSEC sign/unsign operation are workable around through dns_set_zone_options and existing read tools.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A security-hardened MCP server for managing Technitium DNS Server via its HTTP API. It provides 20 tools for DNS zone management, record configuration, and server diagnostics with built-in protections like rate limiting and read-only modes.
      39
      13
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      An MCP server for managing Hetzner DNS zones and RRSets via the Hetzner Cloud API. It enables listing, creating, updating, deleting, importing/exporting zone files, and managing protection and TTLs from MCP clients.
      22
      69 npm
      MIT