OPNsense MCP Server

MCP server for OPNsense firewall operations (ARP, DHCP, logs, rules, interfaces, system status, packet capture).

Use one of two deployment modes:

• STDIO (local): best for Cursor/Claude Code/Continue running the server process directly.

• Streamable HTTP (centralized): best for a shared, long-lived service over HTTPS, at /mcp.

Demo

Query your firewall with Claude Code CLI. Live example with real network data:

Related MCP server: OPNSense MCP Server

Why This Exists

Built this because SSH'ing into the firewall to check logs or grab ARP data got old fast. Now you can ask Claude:

• "What's happening on the network right now?"

• "Show me the latest firewall blocks"

• "Tell me about that host"

• "Capture packets from the suspicious traffic"

Claude handles the firewall query via MCP and gives you analysis + context in one shot. Works on homelab or business deployments equally well.

Quick Start

1) Local setup (required for both modes)

uv venv
source .venv/bin/activate
uv pip install -r requirements.txt
cp examples/.env.example ~/.env

Edit ~/.env:

OPNSENSE_API_KEY=your_api_key
OPNSENSE_API_SECRET=your_api_secret
OPNSENSE_FIREWALL_HOST=your.firewall.host
# HTTP transports only; stdio ignores it. Generate with: openssl rand -hex 32
MCP_SECRET_KEY=

2) Choose mode

Mode A: STDIO (local IDE/client)

Configure your MCP client to launch mcp_start.sh:

{
  "mcpServers": {
    "opnsense-mcp": {
      "command": "/bin/bash",
      "args": ["/absolute/path/to/opnsense-mcp/mcp_start.sh"],
      "cwd": "/absolute/path/to/opnsense-mcp"
    }
  }
}

See full guide: docs/GETTING_STARTED.md.

Mode B: streamable HTTP (centralized service)

Run the Linux installer (Podman + quadlet + Caddy TLS):

sudo bash deploy/install.sh

Clients connect to:

https://<your-hostname>/mcp

The deployed container serves streamable HTTP only. There is no /sse endpoint and no /health route; both answer 404.

Every request must send Authorization: Bearer <MCP_SECRET_KEY>. The server refuses to start on an HTTP transport when the key is blank or a placeholder.

See deployment docs:

• docs/CENTRALIZED_DEPLOY_SPEC.md

• deploy/README.md

• deploy/TLS.md

What Is Available

Primary tools:

• Discovery: arp, dhcp, lldp

• Monitoring: system, get_logs, packet_capture

• Firewall rules: fw_rules, mkfw_rule, set_fw_rule, toggle_fw_rule, rmfw_rule

• Interfaces: interface_list

Full reference: docs/REFERENCE/FUNCTION_REFERENCE.md

What's New (June 2026)

Five PRs landed recently. See docs/FEATURES_UPDATE.md for full details and usage examples.

• Streamable HTTP transport — native FastMCP server supports stdio and streamable-http (MCP spec 2025-03-26). deploy/install.sh deploys streamable HTTP at /mcp.

• DHCP client_id (DUID) support — mk_dhcp_host and move_dhcp_host accept an optional DUID for stateful DHCPv6 matching.

• Semver image tags — main builds are tagged as a prerelease of the next patch after the pyproject.toml version (1.0.1-dev.a1b2c3d after 1.0.0) or release tags (1.0.0).

• Container registry — pinned tags only; :latest is rejected. Set OPNSENSE_MCP_IMAGE_REPO, or build locally with --build-local.

• install.sh readonly fix — Bash readonly clash between install.sh and lib.sh resolved.

Use Cases

• Homelab network troubleshooting — Query firewall logs from terminal, get Claude's take on what's happening

• Security operations — Automate incident triage: "Analyze the last hour of blocks"

• Infrastructure automation — Write MCP-aware scripts that query firewall state dynamically

• DevOps troubleshooting — Quick VLAN/interface status checks without SSH sessions

Feedback

First 10 users get feedback incorporated into the tool. If you find bugs or have ideas, file an issue or discussion.

Where to look first when reviewing

scripts/risk_map.py ranks source files by defect likelihood from git history — churn times fix density — so a review reads the risky files first and can stop early. It finds no bugs; it finds where they concentrate.

python3 scripts/risk_map.py --top 15

CI runs it on every pull request alongside a complexity report (radon) and a security-pattern pass (bandit) in the advisory Insights workflow, which never blocks a merge. Thresholds that gate the build come later, once the numbers are trusted.

Documentation Map

• Start here: docs/GETTING_STARTED.md

• Claude Code specifics: docs/CLAUDE_CODE_INTEGRATION.md

• Centralized deploy spec: docs/CENTRALIZED_DEPLOY_SPEC.md

• Contributor guide: docs/DEVELOPMENT/CONTRIBUTING.md

• Brand assets: docs/assets/

License

This project is released under the MIT License.