Which integrations are available for this server?

Provides tools for querying and managing OPNsense Dnsmasq DHCP state, including static reservations, leases, settings, ranges, options, DHCP tags, domain overrides, and access control, via the official OPNsense API.

How do I use mcp-opnsense-dnsmasq?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-opnsense-dnsmasq show current DHCP leases" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mcp-opnsense-dnsmasq

by Slyke

Overview Schema Related Servers Score Discussions

JavaScript

Remote

mcp-opnsense-dnsmasq

LAN-hosted MCP server for safely querying and managing OPNsense Dnsmasq DHCP state through the official OPNsense API. Codex or other MCP clients authenticate to this server with named Bearer tokens; this server authenticates to OPNsense with API key/secret Basic Auth. OPNsense credentials are never exposed to MCP clients.

Dnsmasq static DHCP reservations are represented by Dnsmasq Hosts entries. This server normalizes those OPNsense model fields (host, ip, hwaddr, descr) into MCP-facing fields (hostname, ip_address, hw_address, description).

dnsmasq_settings_update can edit the Dnsmasq enabled flag, bound interfaces, strict interface binding, DNS listen port, DNSSEC, query logging, DNS cache/query limits, forwarding protection toggles, DHCP disabled interfaces, DHCP FQDN/local-domain behavior, DHCP domain, lease_max, authoritative mode, firewall rule registration, and reply_delay. dhcp_access_block creates or updates a Dnsmasq Host with ignore=true; dhcp_access_unblock clears ignore or deletes an ignore-only host entry. dhcp_access_policy_set maps blacklist to normal dynamic ranges and whitelist to Dnsmasq range mode=static.

Normalized Dnsmasq settings use explicit MCP field names: dns_listen_port maps to Dnsmasq port, strict_interface_binding maps to strictbind, dhcp_no_interface maps to dhcp.no_interface, dhcp_fqdn maps to dhcp.fqdn, dhcp_local_domain maps to dhcp.local, dhcp_authoritative maps to dhcp.authoritative, and register_firewall_rules maps to dhcp.default_fw_rules.

If no readwrite bearer tokens are configured, the server is effectively read-only.

OPNsense Setup

Target: OPNsense 25.7.x Dnsmasq DNS & DHCP.

Enable Dnsmasq.
Enable Dnsmasq DHCP on LAN.
Disable ISC DHCP.
Disable Kea DHCP.
Ensure hidden Interface [no dhcp] does not include LAN.
DHCP authoritative mode is recommended.
DHCP register firewall rules is recommended.

Related MCP server: coreyhines/opnsense-mcp

Creating an OPNsense API Key

Log in to the OPNsense web UI as an administrator.
Go to System > Access > Users.
Create a dedicated local user, for example mcp-dnsmasq, or open an existing dedicated automation user.
Set a strong password even if the account will only use API keys.
In the user account, add the effective privileges OPNsense 25.7 exposes for the APIs this server uses:
- Services: Dnsmasq DNS/DHCP: Settings
- Diagnostics: ARP Table
- Diagnostics: Ping
- Status: Overview
Save the user.
Reopen the user and click the API key add button in the API keys section.
Download or copy the generated key and secret immediately. OPNsense shows the secret only once.
Set OPNSENSE_API_KEY to the generated key and OPNSENSE_API_SECRET to the generated secret.

The Dnsmasq Settings privilege covers Dnsmasq service status, leases, settings, hosts, ranges, options, DHCP tags, domain overrides, and reconfigure APIs in OPNsense 25.7. Status: Overview is needed for interfaces_list, interfaces_get, and inventory interface/VLAN enrichment. Diagnostics: ARP Table is needed for ARP tools and richer conflict/client summaries. The inventory collector also reads the diagnostics NDP table for IPv6 neighbor observations. Diagnostics: Ping is only needed for router_ping and client_summary when ping is requested. Services: Dnsmasq DNS/DHCP: Log File is not used by this MCP server.

The server sends these values to OPNsense as HTTP Basic Auth, with the key as username and the secret as password. Do not use an administrator personal API key for this integration. If OPNsense returns HTTP 403, the API user is authenticated but likely missing one of the listed privileges.

Configuration

Required:

MCP_READ_BEARER_TOKENS
MCP_READWRITE_BEARER_TOKENS
OPNSENSE_BASE_URL
OPNSENSE_API_KEY
OPNSENSE_API_SECRET

Bearer token variables are JSON5 arrays:

[{ name: "reader1", token: "replace-me" }]

Common optional variables:

HTTP_ENABLED=true
HTTP_HOST=0.0.0.0
HTTP_PORT=3000
HTTPS_ENABLED=false
HTTPS_HOST=0.0.0.0
HTTPS_PORT=3443
CONFIG_FILE=./data/config.json5
HISTORY_FILE=./data/history.jsonl
HISTORY_COUNT=50
HISTORY_RECORD_READS=false
INVENTORY_ENABLED=false
INVENTORY_DB_PATH=./data/inventory.sqlite
INVENTORY_POLL_ENABLED=true
INVENTORY_POLL_ON_START=true
INVENTORY_POLL_INTERVAL_MS=120000
INVENTORY_INCLUDE_RAW=false
INVENTORY_COLLECT_LEASES=true
INVENTORY_COLLECT_ARP=true
INVENTORY_COLLECT_NDP=true
INVENTORY_COLLECT_STATIC_HOSTS=true
INVENTORY_COLLECT_INTERFACES=true
INVENTORY_ROW_LIMIT=5000
INVENTORY_RETENTION_DAYS=365
CERTS_DIR=./data/certs
OPNSENSE_TIMEOUT_MS=10000
OPNSENSE_TLS_REJECT_UNAUTHORIZED=true
READY_CHECK_OPNSENSE=false
AUTH_HEALTHCHECKS=false
DEFAULT_INTERFACE=LAN
DEFAULT_INTERFACE_KEY=lan
ALLOWED_STATIC_DHCP_CIDRS=192.168.1.0/24
PROTECTED_IPS=192.168.1.1,192.168.1.254
EXCLUDED_IP_RANGES=
DYNAMIC_DHCP_RANGES=
REJECT_STATIC_INSIDE_DYNAMIC_RANGE=false
STRICT_HOSTNAME=false
AUTO_RECONFIGURE_AFTER_WRITE=true
INCLUDE_RAW_DEFAULT=false
MAX_PING_COUNT=5
MAX_PING_PACKET_SIZE=128

Set HISTORY_RECORD_READS=true or history.recordReads: true to append read-only MCP calls to history for troubleshooting. Read history entries store request metadata, identity name, tool name, redacted arguments, result count when available, and error code when a tool returns an error; they do not store router response bodies.

Set INVENTORY_ENABLED=true or inventory.enabled: true to maintain a local SQLite inventory. Inventory records last-seen observations from Dnsmasq leases, ARP, NDP, static hosts, and interface metadata. It stores device rollups, IP/MAC/interface/VLAN pairings, raw observation history, and poll run summaries. The inventory does not mark devices online or offline; use last_seen_at, last_network_seen_at, and last_seen_source.

Inventory uses Node's built-in node:sqlite module. When running outside the Docker image, use Node.js 22.13 or newer.

For low-token bulk exports, use the authenticated HTTP endpoint GET /inventory/export.csv?table=devices, pairings, observations, or poll_runs. It uses the same bearer-token auth as /mcp and excludes raw_json unless include_raw=true is supplied.

Environment variables override ./data/config.json5. If HTTPS is enabled and server.crt/server.key are missing in CERTS_DIR, the server generates a local self-signed certificate.

Docker

Run the published Docker Hub image:

docker run --rm \
  -p 3000:3000 \
  -v "$PWD/data:/app/data" \
  -e MCP_READ_BEARER_TOKENS='[{name:"reader1",token:"read-token"}]' \
  -e MCP_READWRITE_BEARER_TOKENS='[{name:"admin1",token:"write-token"}]' \
  -e OPNSENSE_BASE_URL='https://opnsense.lan' \
  -e OPNSENSE_API_KEY='replace-me' \
  -e OPNSENSE_API_SECRET='replace-me' \
  -e ALLOWED_STATIC_DHCP_CIDRS='192.168.1.0/24' \
  -e PROTECTED_IPS='192.168.1.1,192.168.1.254' \
  -e CONFIG_FILE="./data/config.json5" \
  -e HISTORY_FILE="./data/history.jsonl" \
  -e CERTS_DIR="./data/certs" \
  slyke/mcp-opnsense-dnsmasq:latest

Build a local image:

docker build -t mcp-opnsense-dnsmasq:local .
docker run --rm \
  -p 3000:3000 \
  -v "$PWD/data:/app/data" \
  -e MCP_READ_BEARER_TOKENS='[{name:"reader1",token:"read-token"}]' \
  -e MCP_READWRITE_BEARER_TOKENS='[{name:"admin1",token:"write-token"}]' \
  -e OPNSENSE_BASE_URL='https://opnsense.lan' \
  -e OPNSENSE_API_KEY='replace-me' \
  -e OPNSENSE_API_SECRET='replace-me' \
  -e ALLOWED_STATIC_DHCP_CIDRS='192.168.1.0/24' \
  -e PROTECTED_IPS='192.168.1.1,192.168.1.254' \
  -e CONFIG_FILE="./data/config.json5" \
  -e HISTORY_FILE="./data/history.jsonl" \
  -e CERTS_DIR="./data/certs" \
  mcp-opnsense-dnsmasq:local

Kubernetes

apiVersion: v1
kind: Secret
metadata:
  name: opnsense-dnsmasq-mcp
type: Opaque
stringData:
  MCP_READ_BEARER_TOKENS: '[{name:"reader1",token:"read-token"}]'
  MCP_READWRITE_BEARER_TOKENS: '[{name:"admin1",token:"write-token"}]'
  OPNSENSE_BASE_URL: 'https://opnsense.lan'
  OPNSENSE_API_KEY: 'replace-me'
  OPNSENSE_API_SECRET: 'replace-me'
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: opnsense-dnsmasq-mcp
spec:
  replicas: 1
  selector:
    matchLabels:
      app: opnsense-dnsmasq-mcp
  template:
    metadata:
      labels:
        app: opnsense-dnsmasq-mcp
    spec:
      containers:
        - name: server
          image: slyke/mcp-opnsense-dnsmasq:latest
          ports:
            - containerPort: 3000
          envFrom:
            - secretRef:
                name: opnsense-dnsmasq-mcp
          env:
            - name: HTTP_ENABLED
              value: "true"
            - name: HTTPS_ENABLED
              value: "false"
            - name: ALLOWED_STATIC_DHCP_CIDRS
              value: "192.168.1.0/24"
            - name: PROTECTED_IPS
              value: "192.168.1.1,192.168.1.254"
            - name: LOG_CONSOLE_FORMAT
              value: json
            - name: LOG_K8S_METADATA_ENABLED
              value: "true"
            - name: K8S_POD_NAME
              valueFrom:
                fieldRef:
                  fieldPath: metadata.name
            - name: K8S_NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace
          readinessProbe:
            httpGet:
              path: /readyz
              port: 3000
          livenessProbe:
            httpGet:
              path: /healthz
              port: 3000

Codex MCP Config

[mcp_servers.opnsense]
url = "http://opnsense-dnsmasq-mcp.lan:3000/mcp"
bearer_token_env_var = "OPNSENSE_MCP_TOKEN"
default_tools_approval_mode = "prompt"

[mcp_servers.opnsense.tools.dnsmasq_status]
approval_mode = "auto"

[mcp_servers.opnsense.tools.dhcp_leases_search]
approval_mode = "auto"

[mcp_servers.opnsense.tools.dhcp_static_list]
approval_mode = "auto"

[mcp_servers.opnsense.tools.dhcp_static_get]
approval_mode = "auto"

[mcp_servers.opnsense.tools.dhcp_static_find_conflicts]
approval_mode = "auto"

[mcp_servers.opnsense.tools.dnsmasq_settings_get]
approval_mode = "auto"

[mcp_servers.opnsense.tools.dhcp_access_blocks_list]
approval_mode = "auto"

[mcp_servers.opnsense.tools.dhcp_access_policy_get]
approval_mode = "auto"

[mcp_servers.opnsense.tools.dhcp_ranges_list]
approval_mode = "auto"

[mcp_servers.opnsense.tools.dhcp_ranges_search]
approval_mode = "auto"

[mcp_servers.opnsense.tools.dhcp_ranges_get]
approval_mode = "auto"

[mcp_servers.opnsense.tools.dhcp_options_list]
approval_mode = "auto"

[mcp_servers.opnsense.tools.dhcp_options_search]
approval_mode = "auto"

[mcp_servers.opnsense.tools.dhcp_options_get]
approval_mode = "auto"

[mcp_servers.opnsense.tools.dhcp_tags_list]
approval_mode = "auto"

[mcp_servers.opnsense.tools.dhcp_tags_search]
approval_mode = "auto"

[mcp_servers.opnsense.tools.dhcp_tags_get]
approval_mode = "auto"

[mcp_servers.opnsense.tools.dhcp_domains_list]
approval_mode = "auto"

[mcp_servers.opnsense.tools.dhcp_domains_search]
approval_mode = "auto"

[mcp_servers.opnsense.tools.dhcp_domains_get]
approval_mode = "auto"

[mcp_servers.opnsense.tools.interfaces_list]
approval_mode = "auto"

[mcp_servers.opnsense.tools.interfaces_get]
approval_mode = "auto"

[mcp_servers.opnsense.tools.arp_list]
approval_mode = "auto"

[mcp_servers.opnsense.tools.arp_search]
approval_mode = "auto"

[mcp_servers.opnsense.tools.mac_vendor_lookup]
approval_mode = "auto"

[mcp_servers.opnsense.tools.client_summary]
approval_mode = "auto"

[mcp_servers.opnsense.tools.router_ping]
approval_mode = "prompt"

[mcp_servers.opnsense.tools.inventory_status]
approval_mode = "auto"

[mcp_servers.opnsense.tools.inventory_devices_search]
approval_mode = "auto"

[mcp_servers.opnsense.tools.inventory_pairings_search]
approval_mode = "auto"

[mcp_servers.opnsense.tools.inventory_observations_search]
approval_mode = "auto"

[mcp_servers.opnsense.tools.inventory_poll_runs_search]
approval_mode = "auto"

[mcp_servers.opnsense.tools.inventory_export_csv]
approval_mode = "prompt"

[mcp_servers.opnsense.tools.inventory_refresh]
approval_mode = "prompt"

[mcp_servers.opnsense.tools.dhcp_static_create]
approval_mode = "prompt"

[mcp_servers.opnsense.tools.dhcp_static_update]
approval_mode = "prompt"

[mcp_servers.opnsense.tools.dhcp_static_delete]
approval_mode = "prompt"

[mcp_servers.opnsense.tools.dnsmasq_settings_update]
approval_mode = "prompt"

[mcp_servers.opnsense.tools.dhcp_access_block]
approval_mode = "prompt"

[mcp_servers.opnsense.tools.dhcp_access_unblock]
approval_mode = "prompt"

[mcp_servers.opnsense.tools.dhcp_access_policy_set]
approval_mode = "prompt"

[mcp_servers.opnsense.tools.dhcp_ranges_update]
approval_mode = "prompt"

[mcp_servers.opnsense.tools.dhcp_ranges_delete]
approval_mode = "prompt"

[mcp_servers.opnsense.tools.dhcp_tags_update]
approval_mode = "prompt"

[mcp_servers.opnsense.tools.dhcp_tags_delete]
approval_mode = "prompt"

[mcp_servers.opnsense.tools.dhcp_domains_update]
approval_mode = "prompt"

[mcp_servers.opnsense.tools.dhcp_domains_delete]
approval_mode = "prompt"

[mcp_servers.opnsense.tools.dnsmasq_reconfigure]
approval_mode = "prompt"

Codex resolves bearer_token_env_var from the Codex host environment when the MCP server initializes. If the OPNsense Dnsmasq MCP tools do not appear, first verify that a fresh WSL2 launch can see the token without printing it:

wsl.exe -d Ubuntu -- bash -lc '[ -n "$OPNSENSE_MCP_TOKEN" ] && echo opnsense=set || echo opnsense=missing'

If that reports missing, but an already-open WSL shell reports set, the token is only available in that interactive shell. For Codex Desktop on Windows, set the token in the Windows user environment and forward it into WSL:

[Environment]::SetEnvironmentVariable("OPNSENSE_MCP_TOKEN", "replace-read-or-readwrite-token", "User")

$current = [Environment]::GetEnvironmentVariable("WSLENV", "User")
$entries = @("OPNSENSE_MCP_TOKEN/u")
$merged = (@($current -split ":" | Where-Object { $_ }) + $entries | Select-Object -Unique) -join ":"
[Environment]::SetEnvironmentVariable("WSLENV", $merged, "User")

Restart Codex Desktop after changing user environment variables, then start a new task. Existing tasks usually will not gain newly initialized MCP tools.

If you run Codex CLI from inside WSL instead, exporting the token before launching Codex is enough:

export OPNSENSE_MCP_TOKEN="replace-read-or-readwrite-token"
codex

If the token is visible but the tools still do not load, check the MCP URL, DNS resolution, and TLS trust separately. For private certificate authorities, configure Codex with a trusted PEM bundle through CODEX_CA_CERTIFICATE or SSL_CERT_FILE.

Tools

Read-only tools:

dnsmasq_status
dnsmasq_settings_get
dhcp_leases_search
dhcp_static_list
dhcp_static_get
dhcp_static_find_conflicts
dhcp_access_blocks_list
dhcp_access_policy_get
dhcp_ranges_list
dhcp_ranges_search
dhcp_ranges_get
dhcp_options_list
dhcp_options_search
dhcp_options_get
dhcp_tags_list
dhcp_tags_search
dhcp_tags_get
dhcp_domains_list
dhcp_domains_search
dhcp_domains_get
interfaces_list
interfaces_get
arp_list
arp_search
mac_vendor_lookup
router_ping
client_summary
history_search
inventory_status
inventory_devices_search
inventory_pairings_search
inventory_observations_search
inventory_poll_runs_search
inventory_export_csv (token-heavy full CSV body through MCP)

Local inventory refresh tool reads OPNsense and writes the SQLite cache, but does not mutate OPNsense:

inventory_refresh

Mutating tools require a readwrite token and include apply, defaulting to false:

dnsmasq_settings_update
dhcp_static_create
dhcp_static_update
dhcp_static_delete
dhcp_access_block
dhcp_access_unblock
dhcp_access_policy_set
dhcp_ranges_update
dhcp_ranges_delete
dhcp_tags_update
dhcp_tags_delete
dhcp_domains_update
dhcp_domains_delete
dnsmasq_reconfigure

CLI MCP Clients

This server exposes Streamable HTTP MCP at /mcp. Start the server first, then point CLI clients at http://<host>:3000/mcp and use one of the configured MCP bearer tokens.

Claude Code

For a one-machine setup, add the remote HTTP server with an Authorization header:

export OPNSENSE_MCP_TOKEN="replace-read-or-readwrite-token"
claude mcp add --transport http opnsense http://opnsense-dnsmasq-mcp.lan:3000/mcp \
  --header "Authorization: Bearer ${OPNSENSE_MCP_TOKEN}"
claude

For a project-shareable config, create .mcp.json and keep the token in the environment:

{
  "mcpServers": {
    "opnsense": {
      "type": "http",
      "url": "http://opnsense-dnsmasq-mcp.lan:3000/mcp",
      "headers": {
        "Authorization": "Bearer ${OPNSENSE_MCP_TOKEN}"
      }
    }
  }
}

Run OPNSENSE_MCP_TOKEN="replace-read-or-readwrite-token" claude, then use /mcp inside Claude Code to confirm the server is connected.

Codex CLI

Codex CLI uses config.toml for Streamable HTTP MCP servers. Add this to ~/.codex/config.toml, or to .codex/config.toml in a trusted project:

[mcp_servers.opnsense]
url = "http://opnsense-dnsmasq-mcp.lan:3000/mcp"
bearer_token_env_var = "OPNSENSE_MCP_TOKEN"
default_tools_approval_mode = "prompt"

Then run:

export OPNSENSE_MCP_TOKEN="replace-read-or-readwrite-token"
codex

Use /mcp in the Codex TUI to confirm the server is connected. codex mcp add is useful for stdio MCP servers; for this HTTP server, use the TOML form above.

Development

npm install
npm test
mkdir -p data/certs
cp .env.example .env
cp config.example.json5 data/config.json5
node --env-file=.env src/index.js

Health endpoints return:

{
  "ok": true,
  "version": "0.0.2",
  "buildHash": "unknown"
}

This server cannot be installed

license - not found

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Slyke/mcp-opnsense-dnsmasq'

If you have feedback or need assistance with the MCP directory API, please join our Discord server