OPNsense MCP Server

A comprehensive MCP server for managing OPNsense firewalls, offering over 300 tools for configuration and monitoring.

GitHub

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 OPNsense MCP Server Network Architecture

Usage in Claude Code image

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 or ~/.cursor/mcp.json globally):

{
  "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"
      }
    }
  }
}

Configuration Options

The server accepts configuration through environment variables:

  • OPNSENSE_URL - OPNsense host URL (required)
  • OPNSENSE_API_KEY - API key for authentication (required)
  • OPNSENSE_API_SECRET - API secret for authentication (required)
  • INCLUDE_PLUGINS - Set to "true" to enable 64 plugin module tools (optional)
  • OPNSENSE_VERIFY_SSL - Set to "false" to disable SSL verification (development only)

How It Works

The modular MCP server provides your AI assistant with 88 module-based tools. Each tool represents an OPNsense module and accepts a method parameter to specify the operation.

Tool Usage Pattern:

{
  "tool": "firewall_manage",
  "arguments": {
    "method": "aliasSearchItem",
    "params": {
      "searchPhrase": "web"
    }
  }
}

Example prompts:

  • "Use core_manage to check system status"
  • "Use firewall_manage to list all firewall aliases"
  • "Use interfaces_manage to get network interface information"
  • "Use plugin_nginx_manage to check the web server configuration"
  • "Use diagnostics_manage to view the ARP table"

The modular approach makes it easy to discover related functionality - all firewall operations are in firewall_manage, all VPN operations in their respective modules (openvpn_manage, ipsec_manage, wireguard_manage).

Available Module Tools

Core Modules (24 tools)

Each tool provides access to all methods within that module:

Tool NameDescriptionExample Methods
core_manageCore system functionsbackupBackups, systemReboot, firmwareInfo
firewall_manageFirewall rules & aliasesaliasSearchItem, filterAddRule, natSearchRule
interfaces_manageNetwork interfacesgetInterfaces, vlanAddItem, setInterface
diagnostics_manageSystem diagnosticsinterfaceGetArp, systemActivityGetActivity
auth_manageAuthenticationuserSearchUser, groupSearchGroup
firmware_manageFirmware updatescheck, update, upgrade, changelog
openvpn_manageOpenVPNinstancesSearch, instancesAdd, serviceReconfigure
ipsec_manageIPsec VPNtunnelSearchPhase1, connectionStatus
wireguard_manageWireGuard VPNserverSearchServer, clientSearchClient
unbound_manageDNS resolverhostOverrideSearchItem, serviceReconfigure
dhcpv4_manageDHCP serversearchLease, addReservation

Plugin Modules (64 tools when enabled)

Popular plugin modules:

Tool NameDescriptionExample Methods
plugin_nginx_manageNginx web servergeneralGet, upstreamSearchUpstream
plugin_haproxy_manageHAProxy load balancerserverSearchServer, statsGet
plugin_caddy_manageCaddy web serverreverseProxySearchDomain, serviceStatus
plugin_bind_manageBIND DNSdomainSearchDomain, recordSearchRecord
plugin_acmeclient_manageLet's EncryptcertificatesSearch, certificatesIssue

Building from Source

If you want to contribute or customize the server:

# Clone the repository
git clone https://github.com/richard-stovall/opnsense-mcp-server.git
cd opnsense-mcp-server

# Install dependencies with Yarn 4.9.2
yarn install

# Build the project
yarn build

# Run locally
yarn start

Development

Development Scripts

yarn generate-tools  # Generate tool definitions
yarn build          # Build the server
yarn build:all      # Generate tools and build
yarn dev            # Run with hot reload
yarn type-check     # Type check without emitting
yarn start          # Start the server

Technology Stack

  • Runtime: Node.js with tsx for TypeScript execution
  • Package Manager: Yarn 4.9.2 with Plug'n'Play
  • Build System: Simple TypeScript compilation to single file
  • Language: TypeScript 5.3+
  • MCP SDK: @modelcontextprotocol/sdk
  • API Client: @richard-stovall/opnsense-typescript-client
  • Validation: Zod for schema validation
  • Testing: Jest with TypeScript support

API Integration

The server uses the @richard-stovall/opnsense-typescript-client package which provides:

  • Complete type safety for all API calls
  • Built-in error handling and retries
  • Support for all 601 OPNsense API endpoints
  • Modern Fetch API based implementation

Example Tool Implementation

const response = await client.system.getStatus();
return {
  content: [
    {
      type: 'text',
      text: JSON.stringify(response.data, null, 2),
    },
  ],
};

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Made with love for the OPNsense community

관련 서버

NotebookLM 웹 임포터

원클릭으로 웹 페이지와 YouTube 동영상을 NotebookLM에 가져오기. 200,000명 이상이 사용 중.

Chrome 확장 프로그램 설치