DEV Community

blizzy
blizzy

Posted on

Talk to Your Firewall: Query OPNsense from tools like Claude Code with MCP

#mcp #opnsense #homelab #ai

Talk to Your Firewall: Query OPNsense from tools like Claude Code with MCP

If you run OPNsense at home or in a lab, you've probably lost time to the same ritual: SSH in, run pfctl -sr, scroll through DHCP leases, or tcpdump a suspicious host. It's not hard — it's just friction.

What if you could ask Claude Code "who's on my network right now?" and get a clean answer without opening a terminal?

That's what opnsense-mcp does. It's a Model Context Protocol (MCP) server that exposes your OPNsense firewall as a set of tools any MCP client can call — stay in your editor, no terminal context-switching.

What You Can Ask

With opnsense-mcp connected, natural language questions become actual firewall queries:

  • "What's happening on the network?" → ARP table + active DHCP leases
  • "Show me the last 20 blocked connections" → Filtered firewall log
  • "Who is 192.168.1.47?" → MAC, hostname, lease status, interface
  • "Capture packets from that host for 30 seconds" → Packet capture + download link
  • "List my firewall rules for port 443" → Rule search with descriptions

The server talks to OPNsense over its native REST API, so responses are live and you stay in your editor.

Quick Start

You need an OPNsense API key. Generate one under System → Access → API.

git clone https://github.com/coreyhines/opnsense-mcp
cd opnsense-mcp
uv venv && source .venv/bin/activate
uv pip install -r requirements.txt

cp examples/.env.example .env
# Edit .env with your API key, secret, and firewall host
Enter fullscreen mode Exit fullscreen mode

Option A: STDIO (local Claude Code / Cursor) 

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

Option B: SSE (shared service) 

sudo bash deploy/install.sh   # Podman + Caddy TLS
# Clients point to https://your-host/sse
Enter fullscreen mode Exit fullscreen mode

A Real Session

Here's what it looks like in practice:

You: "Show me DHCP leases for devices named 'desktop'"

Claude: (calls dhcp tool)

Hostname: desktop-lab, IP: 192.168.10.45, MAC: aa:bb:cc:dd:ee:ff
Status: active, Lease expires: 2026-05-12 08:00

You: "Any blocks in the last 10 minutes?"

Claude: (calls get_logs with time filter)

2026-05-11 18:12:34 BLOCK 10.0.0.55:443 -> 192.168.1.0/24:443 (TCP)
Rule: Default deny / Interface: WAN

No terminal diving. No context-switching. Just questions and answers.

Why I Built This

I manage multiple OPNsense instances and got tired of context-switching between terminals, web dashboards, and my editor. MCP lets the AI client handle the mechanical work — formatting tables, filtering logs, correlating ARP with DHCP — while I stay focused on the actual decision.

The server is intentionally narrow: it doesn't write rules unless you ask it to, and it logs what it touches. You can run it locally (STDIO) or host it as a shared SSE endpoint for a team.

Get It

If you try it, open an issue or PR — I want to hear what workflows it unlocks for you.

Have an OPNsense box in your homelab? Give it a voice.

Top comments (0)