OPNsense MCP Server

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.

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

Related MCP server: OPNsense MCP Server

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

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 .

Run with Docker Compose (recommended)

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.