OPNsense MCP Server

A modular Model Context Protocol (MCP) server that provides 88 module-based tools giving access to over 2000 OPNsense firewall management methods through a type-safe TypeScript interface.

Features

• Modular Architecture - 88 logical tools (one per module) instead of 2000+ individual tools
• Complete API Coverage - Access to 752 core methods and 1271 plugin methods
• Type-Safe - Full TypeScript support with @richard-stovall/opnsense-typescript-client v0.5.3
• Plugin Support - Optional support for 64 plugin modules
• Smart Organization - Related operations grouped by module for easier discovery

The MCP server acts as a bridge between AI assistants (like Claude Desktop) and your OPNsense firewall, providing secure API access through a modular tool interface.

Usage in Claude Desktop

Usage in Claude Code

Installation

As an MCP Server

This package is designed to be used as an MCP (Model Context Protocol) server with AI assistants like Claude Desktop, Cursor, or other MCP-compatible clients.

Prerequisites

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

Install from npm

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

Usage as an MCP Server

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "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 Configuration Methods

Using Command Line Arguments:

{
  "mcpServers": {
    "opnsense": {
      "command": "node",
      "args": [
        "/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"
      ]
    }
  }
}

Enable Plugin Tools: To include all 64 plugin module tools, add "--plugins" to the args or set "INCLUDE_PLUGINS": "true" in env.

Testing the Setup

Once configured, you can test the connection by asking Claude:

• "What MCP tools are available?"
• "Use core_manage to get the system status"
• "Use firewall_manage to search for all aliases"
• "Use interfaces_manage to list all network interfaces"

Troubleshooting Claude Desktop Setup

Connection Issues:

1. Verify your OPNsense API is enabled
2. Check that the API key has appropriate permissions
3. Ensure the IP/hostname is accessible from your machine
4. For self-signed certificates, use --no-verify-ssl or set "OPNSENSE_VERIFY_SSL": "false"

View Server Logs: Check Claude Desktop logs for any error messages from the MCP server.

Test Manually: You can test the server manually before using with Claude Desktop:

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

This should output:

OPNsense MCP server v0.6.0 (modular) started
Core tools: 24 modules
Plugin tools: 64 modules (disabled)
Total available: 24 modules

Cursor Configuration

Add to your Cursor settings (.cursor/mcp.json in your project

... View full README on GitHub