OPNsense

You run an MCP server that exposes modular, type-safe tools to manage an OPNsense firewall. This server acts as a bridge between AI assistants and your firewall, organizing 88 module-based tools so you can perform actions securely and efficiently through a consistent interface.

How to use

Your MCP server provides 88 module-based tools. Each tool corresponds to a logical module and accepts a method parameter to specify the exact operation. Use a tool by selecting its module (for example, firewall_manage) and then choosing a specific method within that module (such as aliasSearchItem or filterAddRule). You can chain common tasks by choosing the appropriate module and method across core operations, VPN, DHCP, DNS, and plugin modules when enabled.

When you compose requests, you structure them to target a module and a method with the required parameters. For example, you would specify the module firewall_manage and a method like aliasSearchItem with search criteria in the parameters. This modular approach groups related operations together for easier discovery and reuse.

How to install

Prerequisites you need before installing the MCP server are: Node.js 18 or higher, an OPNsense firewall with API access enabled, and an API key with its secret.

Install the MCP server globally using the package manager:

npm install -g @richard-stovall/opnsense-mcp-server

Configuration and running

Configure your MCP client to connect to the server using one of the supported execution methods. The examples below show how to run the server from a client that supports MCP configuration files.

{
  "mcpServers": {
    "opnsense": {
      "command": "npx",
      "args": ["-y", "@richard-stovall/opnsense-mcp-server"],
      "env": {
        "OPNSENSE_URL": "https://192.168.1.1",
        "OPNSENSE_API_KEY": "your-api-key",
        "OPNSENSE_API_SECRET": "your-api-secret",
        "OPNSENSE_VERIFY_SSL": "false"
      }
    }
  }
}

Alternative start methods

You can also start the MCP server directly with a node command and inline arguments if you prefer to specify the connection details on the command line.

node /path/to/opnsense-mcp-server/index.js \
  --url https://YOUR-OPNSENSE-IP \
  --api-key YOUR-API-KEY \
  --api-secret YOUR-API-SECRET \
  --no-verify-ssl

Testing the setup

After configuring, you can verify the connection by starting the server and checking that you receive the expected module availability and methods when you query the client. If you need to manually run a quick check, use the node command above and observe the startup messages.

Troubleshooting Claude Desktop setup

If you encounter connection issues, confirm the OPNsense API is enabled and the API key has the necessary permissions. Ensure the firewall’s URL is reachable from your machine. If you use self-signed certificates, run with SSL verification disabled or set the corresponding environment flag.

View logs in your MCP client to identify any errors from the MCP server, and test the server independently before connecting your AI assistant.

Available tools

core_manage

Core system functions such as backup, status checks, and firmware info access.

firewall_manage

Firewall rules and aliases management.

interfaces_manage

Network interfaces discovery and configuration.

diagnostics_manage

System diagnostics and status checks.

auth_manage

User and group authentication operations.

firmware_manage

Firmware update and changelog access.

openvpn_manage

OpenVPN client/server management.

ipsec_manage

IPsec VPN management and status.

wireguard_manage

WireGuard VPN management.

unbound_manage

DNS resolver configurations and overrides.

dhcpv4_manage

DHCPv4 server and lease management.

plugin_nginx_manage

Nginx web server plugin related operations.

plugin_haproxy_manage

HAProxy plugin related operations.

plugin_caddy_manage

Caddy web server plugin related operations.

plugin_bind_manage

BIND DNS plugin related operations.

plugin_acmeclient_manage

Let's Encrypt certificate management plugin operations.