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
Modular MCP server for OPNsense firewall management - 88 tools providing access to 2000+ methods through AI assistants
星數
90
工具
—
可用率
—
Complete API Coverage - Access to 752 core methods and 1271 plugin methods
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
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.
"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 Name
Description
Example Methods
core_manage
Core system functions
backupBackups, systemReboot, firmwareInfo
firewall_manage
Firewall rules & aliases
aliasSearchItem, filterAddRule, natSearchRule
interfaces_manage
Network interfaces
getInterfaces, vlanAddItem, setInterface
diagnostics_manage
System diagnostics
interfaceGetArp, systemActivityGetActivity
auth_manage
Authentication
userSearchUser, groupSearchGroup
firmware_manage
Firmware updates
check, update, upgrade, changelog
openvpn_manage
OpenVPN
instancesSearch, instancesAdd, serviceReconfigure
ipsec_manage
IPsec VPN
tunnelSearchPhase1, connectionStatus
wireguard_manage
WireGuard VPN
serverSearchServer, clientSearchClient
unbound_manage
DNS resolver
hostOverrideSearchItem, serviceReconfigure
dhcpv4_manage
DHCP server
searchLease, addReservation
Plugin Modules (64 tools when enabled)
Popular plugin modules:
Tool Name
Description
Example Methods
plugin_nginx_manage
Nginx web server
generalGet, upstreamSearchUpstream
plugin_haproxy_manage
HAProxy load balancer
serverSearchServer, statsGet
plugin_caddy_manage
Caddy web server
reverseProxySearchDomain, serviceStatus
plugin_bind_manage
BIND DNS
domainSearchDomain, recordSearchRecord
plugin_acmeclient_manage
Let's Encrypt
certificatesSearch, 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