Skip to main content

OPNsense MCP Server

CI PyPI License: MIT Built with SpecKit

GitHub: https://github.com/tazendor/opnsense-mcp-server

A Python Model Context Protocol server that exposes the OPNsense REST API to AI clients such as Claude Desktop and Claude Code.

What it does

The server proxies 43 OPNsense API endpoints across eight domains as MCP tools, letting AI clients query and mutate firewall state through natural language.

Domain Tools Capabilities
System 3 Status, firmware check, config backup
Firewall 17 Rule and alias CRUD, NAT port forwards, apply
Interfaces 4 Interface list, config, ARP/NDP tables
DHCP 3 Lease list, settings, static mappings
Routes 5 Static route CRUD and apply
DNS 6 Unbound settings and host override CRUD
IDS 1 Ruleset list
Services 4 Start/stop/restart/status for core modules

Mutating operations follow OPNsense's staged-then-apply model: changes are staged by _add/_update/_delete tools and committed by the corresponding _apply tool.

Requirements

  • Python 3.12+
  • uv
  • OPNsense 26.1+ with API access enabled

Compatibility: Tested against OPNsense 26.1.10. The 26.x release series made breaking REST API changes — Kea replaced ISC DHCPv4 (kea/* paths), port-forward NAT moved to Destination NAT (firewall/d_nat/*), and the system status endpoint changed. Older releases are not supported.

Installation

pip install tazendor-opnsense-mcp

Or from source:

git clone https://github.com/tazendor/opnsense-mcp-server.git
cd opnsense-mcp-server
uv sync

Configuration

Environment variables

Variable Required Default Description
OPNSENSE_URL yes — OPNsense base URL; must start with https://
OPNSENSE_API_KEY yes — OPNsense API key
OPNSENSE_API_SECRET yes — OPNsense API secret
OPNSENSE_VERIFY_TLS no true Set false to skip TLS verification (self-signed certs)
OPNSENSE_TRANSPORT no stdio stdio or http
OPNSENSE_HTTP_HOST no 127.0.0.1 Bind address for HTTP transport
OPNSENSE_HTTP_PORT no 8000 Port for HTTP transport
OPNSENSE_CONNECT_TIMEOUT no 10.0 Seconds to wait for OPNsense TCP connection
OPNSENSE_READ_TIMEOUT no 60.0 Seconds to wait for OPNsense API response

Config file

Create ~/.config/opnsense-mcp/config.toml:

url = "https://192.168.1.1"
api_key = "your-api-key"
api_secret = "your-api-secret"
verify_tls = false      # omit or set true for valid certificates
transport = "stdio"     # or "http"
http_host = "127.0.0.1"
http_port = 8000
connect_timeout = 10.0
read_timeout = 60.0

Environment variables override config file values. The config file is optional — environment variables alone are sufficient.

Running

stdio transport (Claude Desktop / Claude Code)

stdio is the default and recommended transport. The MCP client launches the server as a subprocess and communicates over stdin/stdout. No network port is opened.

uv run opnsense-mcp

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "opnsense": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/opnsense-mcp-server", "opnsense-mcp"],
      "env": {
        "OPNSENSE_URL": "https://192.168.1.1",
        "OPNSENSE_API_KEY": "your-api-key",
        "OPNSENSE_API_SECRET": "your-api-secret"
      }
    }
  }
}

Claude Code — add to .mcp.json in your project root, or ~/.claude/mcp.json for global use:

{
  "mcpServers": {
    "opnsense": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/opnsense-mcp-server", "opnsense-mcp"],
      "env": {
        "OPNSENSE_URL": "https://192.168.1.1",
        "OPNSENSE_API_KEY": "your-api-key",
        "OPNSENSE_API_SECRET": "your-api-secret"
      }
    }
  }
}

If you installed via pip install tazendor-opnsense-mcp, replace the uv run --project ... invocation with the installed entry point:

{
  "mcpServers": {
    "opnsense": {
      "command": "opnsense-mcp",
      "env": {
        "OPNSENSE_URL": "https://192.168.1.1",
        "OPNSENSE_API_KEY": "your-api-key",
        "OPNSENSE_API_SECRET": "your-api-secret"
      }
    }
  }
}

Streamable HTTP transport

HTTP transport runs the server as a long-lived process that listens for MCP connections over HTTP. Use this when you want multiple clients to share a single server instance, or when stdio is not practical (e.g. a remote host or a containerised deployment).

Start the server:

OPNSENSE_TRANSPORT=http \
OPNSENSE_HTTP_HOST=127.0.0.1 \
OPNSENSE_HTTP_PORT=8000 \
uv run opnsense-mcp

The server binds at http://<HTTP_HOST>:<HTTP_PORT>/mcp. With the defaults above that is http://127.0.0.1:8000/mcp.

Security: HTTP mode does not enforce payload size limits, rate limiting, or client authentication. The server prints a warning to this effect at startup. For anything beyond local use, place the server behind a reverse proxy that adds those controls. A Caddyfile.example is included in the repository — copy it to Caddyfile, replace the placeholders, and run caddy run. It configures HTTP Basic auth, a 1 MB request body limit, and per-IP rate limiting.

Claude Code — add to .mcp.json:

{
  "mcpServers": {
    "opnsense": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Other MCP clients — connect to http://127.0.0.1:8000/mcp using the MCP Streamable HTTP transport. The server follows the standard MCP session handshake: send an initialize request, then a notifications/initialized notification (both carrying the mcp-session-id header returned by the server), then issue tool calls.

Docker

The server ships with a production-ready Docker image built on python:3.12-slim-bookworm. Dependencies are installed in the build stage via uv, then only the .venv is copied to the runtime stage — no build tooling in the final image. The container runs as a non-root user (uid 1000).

Build

docker build -t opnsense-mcp .

Copy .env.example to .env and fill in your credentials:

cp .env.example .env
# edit .env
docker compose up -d

The server listens on http://127.0.0.1:8000/mcp. The compose file binds only to 127.0.0.1 — to expose on a LAN, change the ports entry and put a reverse proxy in front for auth.

Run without Compose

docker run -d \
  --name opnsense-mcp \
  -p 127.0.0.1:8000:8000 \
  --env-file .env \
  --read-only --tmpfs /tmp \
  --cap-drop ALL \
  --security-opt no-new-privileges:true \
  opnsense-mcp

stdio via Docker

You can run the server in stdio mode so that a client such as Claude Desktop or Claude Code spawns it as a subprocess:

{
  "mcpServers": {
    "opnsense": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--read-only", "--tmpfs", "/tmp",
        "--cap-drop", "ALL",
        "--security-opt", "no-new-privileges:true",
        "--env-file", "/path/to/.env",
        "opnsense-mcp",
        "opnsense-mcp"
      ]
    }
  }
}

The -i flag keeps stdin open so the MCP protocol can flow through it. Omit -p — no port is needed in stdio mode.

Development

# Run unit and contract tests (no OPNsense instance needed)
uv run pytest -m "not integration"

# Run integration tests against a live instance
OPNSENSE_URL=https://... OPNSENSE_API_KEY=... OPNSENSE_API_SECRET=... \
  uv run pytest -m integration -v

# Quality gates
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/
uv run mypy --strict src/

All unit and contract tests pass without a live OPNsense instance (pytest -m "not integration").

Security notes

  • HTTPS enforced: the server refuses to start with an http:// URL.
  • Credentials never logged: api_key and api_secret flow only into the HTTP Authorization header and are absent from all log output.
  • Structured audit log: every OPNsense API call is logged to stderr as a JSON line with stable fields — ts (UTC ISO-8601), req_id (UUID v4 per request), method, path, status_code, outcome. Example:
    {"ts":"2026-06-28T12:00:00+00:00","req_id":"a3f1c2d4-...","method":"GET","path":"core/system/status","status_code":200,"outcome":"success"}
    
  • Input validation: UUID and alias-name parameters are validated against strict allowlist patterns before being interpolated into API paths, preventing path-traversal attempts.
  • TLS verification warning: when OPNSENSE_VERIFY_TLS=false, a warning is printed at startup.
  • HTTP transport warning: when HTTP transport is enabled, a warning is printed at startup listing the controls that are not enforced (payload limits, rate limiting, client authentication). See the Streamable HTTP transport section for hardening guidance.

Metadata

Release files for tazendor-opnsense-mcp 0.2.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tazendor-opnsense-mcp 0.2.4
File Size Uploaded Provenance Actions
tazendor_opnsense_mcp-0.2.4.tar.gz 140.7 kB With provenance Details for tazendor_opnsense_mcp-0.2.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tazendor-opnsense-mcp 0.2.4
File Interpreter ABI Platform Actions
tazendor_opnsense_mcp-0.2.4-py3-none-any.whl Python 3 none any Details for tazendor_opnsense_mcp-0.2.4-py3-none-any.whl

Total release size: 159.1 kB

Release files / tazendor_opnsense_mcp-0.2.4.tar.gz

Download URL tazendor_opnsense_mcp-0.2.4.tar.gz
Size 140.7 kB
Tags Source
SHA-256 checksum
How to use checksums
0881eca06dadd4fff0bc914619ef448ebc03ca2974cfaf110db42e9fdd8b05d7
BLAKE2b-256 checksum
How to use checksums
de9e0131c00e5fea6cbc8e379c6a3bd1471e697443580ab2bdb9c88d41cc6ac7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 29, 2026.

Transparency log

Release files / tazendor_opnsense_mcp-0.2.4-py3-none-any.whl

Download URL tazendor_opnsense_mcp-0.2.4-py3-none-any.whl
Size 18.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
275d27f1d0d1a7fc8e1b1a351a87c3d4c73bce525fb550097928a3044569a3ac
BLAKE2b-256 checksum
How to use checksums
7d05e4545389705200524d94d0ffd69f77ec97338940101ebcb12a0aea7daf14
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 29, 2026.

Transparency log

Security for tazendor-opnsense-mcp 0.2.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for tazendor_opnsense_mcp-0.2.4.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 29, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page