Skip to main content
Glama
Sign In
Technitium MCP Secure

Technitium MCP Secure

by rosschurchill
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

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: mcp-technitium-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: zone (required), domain (required), type (required), value (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: zone (required), domain (required), type (required), value (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: pageNumber, entriesPerPage, domain, clientIp, +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: enableBlocking, forwarders, forwarderProtocol, dnssecValidation, +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, zoneTransferAllowedNetworks, notifyNameServers.

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: zone (required), domain (required), type (required), value (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.

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.7/5.0

    Scored across 39 tools

    Disambiguation5/5

    All tools have distinct purposes, clearly differentiated by verb and noun. Even related tools like dns_flush_cache vs dns_delete_cached are scoped differently (entire cache vs specific domain). No ambiguity.

    Naming Consistency5/5

    All 39 tools follow the dns_verb_noun pattern in snake_case. Verbs are imperative and descriptive, and the pattern is rigidly applied. Only very minor variations exist (e.g., dns_health_check vs dns_check_update), but they are still consistent overall.

    Tool Count4/5

    39 tools is large but justified given the broad scope of DNS server management (zones, records, blocking, caching, apps, settings, stats, DNSSEC). Some tools could be consolidated (e.g., dns_allow_domain and dns_remove_allowed are separate, but that's acceptable). Slightly over the typical range but not chaotic.

    Completeness5/5

    The tool set covers virtually all common DNS operations: CRUD for zones and records, block/allow management, caching, apps lifecycle, settings, stats, DNSSEC, logging, and health checks. No obvious gaps for the intended purpose of managing a Technitium DNS server.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Resources

    Related MCP Connectors

    Related MCP Servers