The OPNSense MCP Server enables Infrastructure as Code (IaC) management of OPNsense firewalls through comprehensive API integration. With this server, you can:
Configure OPNsense Connection: Set up host, API key, and secret for firewall communication
Test Connectivity: Verify API connection and authentication
Manage VLANs: List, create, update, delete, and retrieve VLAN details
Control Firewall Rules: List, create, update, delete, enable/disable, and search rules; supports predefined rule presets
Handle Backups: Create, list, and restore configuration backups
Network Operations: Retrieve available network interfaces and configure isolated networks
DNS Management: Manage DNS blocklists
IaC Integration: Declaratively manage OPNsense infrastructure using JSON or JavaScript
Provides tools for managing OPNSense firewalls, including VLAN creation and management, firewall rule configuration, network interface queries, and DHCP lease management
Implements an audit database for tracking changes made through the OPNSense MCP server
Used as an optional cache layer for improved performance in Phase 3 of the OPNSense MCP server
OPNsense MCP Server
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+ and npm
- OPNsense firewall (v24.7+ recommended)
- API credentials for OPNsense
- SSH access (optional, for advanced features)
Quick Start
- Install the package:
- Create a
.env
file with your credentials:
- Start the MCP server:
Usage with Claude Desktop
Add to your Claude Desktop configuration (claude_desktop_config.json
):
Common Use Cases
Fix DMZ NAT Issues
Create Firewall Rules
Diagnose Routing Issues
Execute CLI Commands
MCP Tools Reference
The server provides 50+ MCP tools organized by category:
Firewall Tools
firewall_list_rules
- List all firewall rulesfirewall_create_rule
- Create a new rulefirewall_update_rule
- Update existing rulefirewall_delete_rule
- Delete a rulefirewall_apply_changes
- Apply pending changes
NAT Tools
nat_list_outbound
- List outbound NAT rulesnat_set_mode
- Set NAT modenat_create_outbound_rule
- Create NAT rulenat_fix_dmz
- Fix DMZ NAT issuesnat_analyze_config
- Analyze NAT configuration
Network Tools
arp_list
- List ARP table entriesrouting_diagnostics
- Diagnose routing issuesrouting_fix_all
- Auto-fix routing problemsinterface_list
- List network interfacesvlan_create
- Create VLAN
System Tools
system_execute_command
- Execute CLI commandbackup_create
- Create configuration backupservice_restart
- Restart a service
For a complete list, see docs/api/mcp-tools.md.
Documentation
Testing
The repository includes comprehensive testing utilities:
Development
Building from Source
Project Structure
Troubleshooting
API Authentication Failed
- Verify API key and secret are correct
- Ensure API access is enabled in OPNsense
- Check firewall rules allow API access
SSH Connection Failed
- Verify SSH credentials in
.env
- Ensure SSH is enabled on OPNsense
- Check user has appropriate privileges
NAT Features Not Working
- NAT management requires SSH access
- Add SSH credentials to environment variables
- Test with:
npx tsx scripts/test/test-nat-ssh.ts
Contributing
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Support
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: Full Documentation
Acknowledgments
- Built for use with Anthropic's Claude
- Implements the Model Context Protocol
- Designed for OPNsense firewall
Version: 0.8.2 | Status: Production Ready | Last Updated: August 2025
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
A server that enables managing OPNSense firewalls through natural language interactions with Claude Desktop, supporting VLAN management, firewall rules configuration, and network interface queries.
- Features
- Installation
- Usage with Claude Desktop
- Common Use Cases
- MCP Tools Reference
- Documentation
- Testing
- Development
- Troubleshooting
- Contributing
- License
- Support
- Acknowledgments
Related Resources
Related MCP Servers
- AsecurityAlicenseAqualityLets you use Claude Desktop, or any MCP Client, to use natural language to accomplish things on your Cloudflare account.Last updated -21,1592,918Apache 2.0
- AsecurityAlicenseAqualityEnables natural language interaction with Azure services through Claude Desktop, supporting resource management, subscription handling, and tenant selection with secure authentication.Last updated -9415MIT License
- -securityAlicense-qualityA production-grade server that enables natural language interaction with pfSense firewalls through Claude Desktop and other GenAI applications, supporting multiple access levels and functional categories.Last updated -14MIT License
- -securityFlicense-qualityProvides system monitoring and management capabilities for Claude CLI, allowing users to view system information, track resource usage, and manage processes through natural language commands.Last updated -