Opnsense MCP

What coreyhines/opnsense-mcp MCP server does

coreyhines/opnsense-mcp MCP server connects an MCP client to an OPNsense firewall through its API. It gives an agent access to network and firewall state that would otherwise require navigating the firewall interface or logging in over SSH. The project is suited to homelab troubleshooting, security triage, infrastructure automation, and DevOps checks across VLANs or interfaces.

The server includes read-oriented discovery and monitoring operations, along with firewall rule operations. It can retrieve ARP, DHCP, and LLDP information; inspect logs and system status; list interfaces; capture packets; and create, modify, enable or disable, and remove firewall rules. The README also documents DHCP host creation and movement with optional DHCPv6 DUID support.

How it works

The MCP process uses OPNsense API credentials and a configured firewall hostname. An MCP client sends tool requests to the server, which performs the corresponding operation against OPNsense and returns the result for the client or agent to interpret.

Two deployment styles are documented. STDIO runs the server locally as a child process and is intended for clients such as Cursor, Claude Code, or Continue. SSE runs a centralized, long-lived service that clients access through an HTTPS endpoint. The native FastMCP server also supports streamable HTTP in addition to STDIO and SSE.

Setup and configuration

Local setup uses a Python virtual environment. The documented sequence creates a virtual environment with uv, activates it, installs dependencies from requirements.txt, and copies the example environment file to ~/.env. Configuration requires these values:

• OPNSENSE_API_KEY for the OPNsense API key
• OPNSENSE_API_SECRET for the OPNsense API secret
• OPNSENSE_FIREWALL_HOST for the firewall host
• MCP_SECRET_KEY for the MCP service

For STDIO, configure the MCP client to launch the repository's mcp_start.sh script with Bash, using absolute paths for the script and working directory. For centralized SSE, the documented Linux installer uses Podman, quadlet, and Caddy TLS configuration. Clients connect to the resulting /sse endpoint on the configured hostname.

Tools and capabilities

The documented primary tool groups are:

• Discovery: arp, dhcp, and lldp
• Monitoring: system, get_logs, and packet_capture
• Firewall rules: fw_rules, mkfw_rule, set_fw_rule, toggle_fw_rule, and rmfw_rule
• Interfaces: interface_list

The firewall rule operations cover both inspection and mutation. Packet capture and log retrieval support investigations, while ARP, DHCP, LLDP, system, and interface queries provide current network context. The full function reference is maintained in the repository documentation.

Limitations and notes

coreyhines/opnsense-mcp MCP server requires access to an OPNsense API and the corresponding credentials; it is not a standalone firewall data source. The README provides deployment instructions for Linux-based centralized service installation and does not describe a hosted instance supplied by the project. The local configuration examples contain placeholders that must be replaced with the target firewall and locally chosen secret values.

The project documents Cursor, Claude Code, and Continue for direct STDIO use. It does not provide a specific Claude Desktop configuration in the supplied material. SSE deployment is intended for shared access and requires the additional service setup described by the project, rather than only launching the local MCP script.