Technitium MCP Secure Server

You can run a security-hardened MCP server that manages Technitium DNS Server through its HTTP API. This MCP server provides a robust set of tools, strict input validation, read-only modes for safe monitoring, and safeguards for destructive actions, all designed to help you administer DNS zones, records, blocks, caches, and logs from MCP-compatible clients.

How to use

You interact with the Technitium MCP Secure server using an MCP-compatible client. Connect to the server’s API over HTTPS by providing a valid API token, and you can perform read-only queries or write operations to manage DNS zones, records, blocks, and settings. Your client will send structured requests to the server, and you will receive sanitized responses with clear status information. Enable read-only mode if you only want to monitor and query data without making changes. Destructive actions require explicit confirmation to prevent accidental data loss.

How to install

Prerequisites: ensure you have Node.js version 18 or higher installed on your host machine.

Step-by-step setup and run flow you can follow exactly as shown:

# Clone and build
git clone https://github.com/rosschurchill/technitium-mcp-secure.git
cd technitium-mcp-secure
npm install
npm run build

# Start the MCP server (example runtime command)
node dist/index.js

# Register with Claude Code (example, to obtain an API token)
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
n

Additional content

All configuration is via environment variables. The required and optional variables guide how your MCP server authenticates to Technitium DNS Server and how it behaves in different network scenarios.

Configuration

Environment variables control how the MCP server connects to Technitium DNS Server and how it authenticates clients. Key variables include the server URL, the API token, and options for read-only mode and HTTP usage.

| 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 |

Security and tokens

Authentication supports multiple methods with a clear precedence: token, token file, then password. Tokens offer safer long-term authentication compared to passwords and can be revoked independently.

All sensitive environment variables are cleared from memory after being read to reduce the risk of leakage.

Rate limits and audit

Rate limits help prevent abuse: global limits and stricter limits for destructive actions so you can plan capacity and protect your DNS infrastructure.

Audit logs are produced as structured JSONL to standard error, including timestamps, tool names, sanitized arguments, results, and duration.

Troubleshooting and notes

If you operate over a local network without TLS, you must explicitly enable HTTP in the client configuration. A warning is emitted if credentials are sent in plaintext.

Available tools

dns_health_check

Report server version, uptime, forwarder config, and failure rate

dns_get_stats

Query statistics including top clients, domains, and blocked entries

dns_resolve

Test DNS resolution through the MCP server

dns_list_zones

List all configured DNS zones

dns_zone_options

Retrieve zone DNSSEC, transfer, and notify settings

dns_list_records

List DNS records within a zone

dns_list_blocked

List domains currently blocked by the server

dns_list_allowed

List domains that are whitelisted or allowed despite blocks

dns_list_cache

List cached zones and entries

dns_get_settings

Retrieve full server settings

dns_query_logs

Query DNS logs with filters

dns_list_apps

List installed DNS applications

dns_create_zone

Create a new DNS zone

dns_delete_zone

Delete a DNS zone (requires confirm: true)

dns_add_record

Add a DNS record to a zone

dns_update_record

Update an existing DNS record

dns_delete_record

Delete a DNS record (requires confirm: true)

dns_block_domain

Block a domain from resolution

dns_allow_domain

Allow a domain (bypass block lists)

dns_flush_cache

Flush the DNS cache (requires confirm: true)