vespo92/OPNSenseMCP

A Model Context Protocol (MCP) server for comprehensive OPNsense firewall management. This server enables AI assistants like Claude to directly manage firewall configurations, diagnose network issues, and automate complex networking tasks.
Features
🔥 Firewall Management
- Complete CRUD operations for firewall rules
- Proper handling of API-created "automation rules"
- Inter-VLAN routing configuration
- Batch rule creation and management
- Enhanced persistence with multiple fallback methods
🌐 NAT Configuration (SSH-based)
- Outbound NAT rule management
- NAT mode control (automatic/hybrid/manual/disabled)
- No-NAT exception rules for inter-VLAN traffic
- Automated DMZ NAT issue resolution
- Direct XML configuration manipulation
🔍 Network Diagnostics
- Comprehensive routing analysis
- ARP table inspection with vendor identification
- Interface configuration management
- Network connectivity troubleshooting
- Auto-fix capabilities for common issues
🖥️ SSH/CLI Execution
- Direct command execution on OPNsense
- Configuration file manipulation
- System-level operations not available via API
- Service management and restarts
📊 Additional Capabilities
- VLAN management
- DHCP lease viewing and management
- DNS blocklist configuration
- HAProxy load balancer support
- Configuration backup and restore
- Infrastructure as Code support
Installation
Prerequisites
- Node.js 18+ to run the server (Bun 1.1.39+ to develop on it)
- OPNsense firewall (v24.7+ recommended)
- API credentials for OPNsense
- SSH access (optional, for advanced features)
Quick Start with npm
1. Install the package:
2. Create a .env file with your credentials:
3. Start the MCP server:
⚠️ Safety Modes (read this before pointing at a production router)
By default this server can make live, immediate changes to your firewall —
add/delete rules, change NAT, restart services, run whitelisted shell
commands over SSH. Two environment variables (operator-only — a tool call
can never set or override them) add a safety net:
| Variable | Effect |
|----------|--------|
| OPNSENSE_READ_ONLY=true | Every mutating API call and every non-read-only SSH command is rejected before it's sent. Write-capable tools are also hidden from the tool list, so the model never sees them as an option. |
| OPNSENSE_DRY_RUN=true | Mutating calls are simulated instead of sent — you get a log line and a synthetic success response describing what *would* have happened, with no request reaching the router. |
Both are enforced at the two lowest-level chokepoints this server uses to
reach the router — the API client and the SSH executor — so they apply
uniformly across all 140+ tools, not on a per-tool basis. If both are set,
OPNSENSE_READ_ONLY wins.
See CONFIGURATION.md for the config
reference, or docs/features/safety-modes.md
for how it works under the hood.
Quick Start with Bun (Faster)
Bun provides significantly faster startup times and better performance.
1. Install Bun (if not already installed):
2. Clone and install:
3. Create your .env file (same as npm version above)
4. Run with Bun:
Using Bun with Claude Desktop
Usage with Claude Desktop (npm)
Add to your Claude Desktop configuration (claude_desktop_config.json):