opnsense

This MCP server exposes 88 modular tools that map to OPNsense modules, enabling an AI assistant to manage your firewall through a type-safe interface. Each tool like firewall_manage or interfaces_manage represents a module and accepts a method parameter to specify the exact operation, e.g., to search for a firewall alias you would call the firewall_manage tool with method set to aliasSearchItem and provide the necessary parameters. The plugin system can extend capabilities with 64 additional plugin modules if enabled. To use, configure your MCP client (Claude Desktop, Cursor, or other MCP-compatible clients) to connect to the server using the provided URL, API key, and secret, and ensure SSL verification settings match your environment. Typical prompts include asking for system status via core_manage, listing aliases with firewall_manage, or retrieving network interfaces with interfaces_manage. When plugins are enabled, you can access additional capabilities such as Nginx management via plugin_nginx_manage or other plugin modules depending on your configuration.

Prerequisites:

• Node.js 18 or higher
• An OPNsense firewall with API access enabled
• An API key and API secret from OPNsense

Install from npm:

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

Configure the MCP server (example for Claude/Cursor integration):

{
  "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 run (manual test):

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

Test an available tool, e.g., core_manage to check system status by issuing a request with tool: "core_manage" and method: "systemStatus" in your MCP client.

Tips and notes:

• Environment variables: OPNSENSE_URL, OPNSENSE_API_KEY, OPNSENSE_API_SECRET are required; OPNSENSE_VERIFY_SSL can be set to false to disable SSL verification during development.
• To enable all 64 plugin tools, include the flag or env INCLUDE_PLUGINS=true when starting the server.
• If you encounter connection issues, verify that the OPNsense API is accessible from the host running the MCP server and that the API credentials have appropriate permissions.
• Check server logs for startup messages like the version and available module counts (e.g., Core tools: 24 modules, Plugin tools: 64 modules).
• You can run the MCP server locally for testing before integrating with Claude Desktop or Cursor.