OPNSense MCP Server

Manage OPNsense firewalls using Infrastructure as Code (IaC) principles.

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.

- 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

- 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

- Comprehensive routing analysis
- ARP table inspection with vendor identification
- Interface configuration management
- Network connectivity troubleshooting
- Auto-fix capabilities for common issues

- Direct command execution on OPNsense
- Configuration file manipulation
- System-level operations not available via API
- Service management and restarts

- VLAN management
- DHCP lease viewing and management
- DNS blocklist configuration
- HAProxy load balancer support
- Configuration backup and restore
- Infrastructure as Code support

- Node.js 18+ or Bun 1.0+
- OPNsense firewall (v24.7+ recommended)
- API credentials for OPNsense
- SSH access (optional, for advanced features)
- Create a.envfile with your credentials:

# Required OPNSENSE_HOST=https://your-opnsense-host:port OPNSENSE_API_KEY=your-api-key OPNSENSE_API_SECRET=your-api-secret OPNSENSE_VERIFY_SSL=false # Optional - for SSH features OPNSENSE_SSH_HOST=your-opnsense-host OPNSENSE_SSH_USERNAME=root OPNSENSE_SSH_PASSWORD=your-password # Or use SSH key # OPNSENSE_SSH_KEY_PATH=~/.ssh/id_rsa

Bunprovides significantly faster startup times and better performance.

curl -fsSL https://bun.sh/install | bash

git clone https://github.com/vespo92/OPNSenseMCP.git cd OPNSenseMCP bun install

# Development with hot reload bun run dev:bun # Production bun run start:bun

{ "mcpServers": { "opnsense": { "command": "bun", "args": ["run", "/path/to/OPNSenseMCP/src/index.ts"], "env": { "OPNSENSE_HOST": "https://your-opnsense:port", "OPNSENSE_API_KEY": "your-key", "OPNSENSE_API_SECRET": "your-secret", "OPNSENSE_VERIFY_SSL": "false" } } } }

Add to your Claude Desktop configuration (claude_desktop_config.json):

{ "mcpServers": { "opnsense": { "command": "npx", "args": ["opnsense-mcp-server"], "env": { "OPNSENSE_HOST": "https://your-opnsense:port", "OPNSENSE_API_KEY": "your-key", "OPNSENSE_API_SECRET": "your-secret", "OPNSENSE_VERIFY_SSL": "false" } } } }

// Automatically fix DMZ to LAN routing await mcp.call('nat_fix_dmz', { dmzNetwork: '10.0.6.0/24', lanNetwork: '10.0.0.0/24' });

// Allow NFS from DMZ to NAS await mcp.call('firewall_create_rule', { action: 'pass', interface: 'opt8', source: '10.0.6.0/24', destination: '10.0.0.14/32', protocol: 'tcp', destination_port: '2049', description: 'Allow NFS from DMZ' });

// Run comprehensive routing diagnostics await mcp.call('routing_diagnostics', { sourceNetwork: '10.0.6.0/24', destNetwork: '10.0.0.0/24' });

// Run any OPNsense CLI command await mcp.call('system_execute_command', { command: 'pfctl -s state | grep 10.0.6' });

The server provides 50+ MCP tools organized by category:

- firewall_list_rules- List all firewall rules
- firewall_create_rule- Create a new rule
- firewall_update_rule- Update existing rule
- firewall_delete_rule- Delete a rule
- firewall_apply_changes- Apply pending changes

- nat_list_outbound- List outbound NAT rules
- nat_set_mode- Set NAT mode
- nat_create_outbound_rule- Create NAT rule
- nat_fix_dmz- Fix DMZ NAT issues
- nat_analyze_config- Analyze NAT configuration

- arp_list- List ARP table entries
- routing_diagnostics- Diagnose routing issues
- routing_fix_all- Auto-fix routing problems
- interface_list- List network interfaces
- vlan_create- Create VLAN

- system_execute_command- Execute CLI command
- backup_create- Create configuration backup
- service_restart- Restart a service

For a complete list, seedocs/api/mcp-tools.md.

- Quick Start Guide
- Configuration Guide
- NAT Management
- SSH/CLI Execution
- Firewall Rules
- Troubleshooting

# Test NAT functionality npx tsx scripts/test/test-nat-ssh.ts # Test firewall rules npx tsx scripts/test/test-rules.ts # Test routing diagnostics npx tsx scripts/test/test-routing.ts # Run all tests npm test

git clone https://github.com/vespo92/OPNSenseMCP.git cd OPNSenseMCP npm install npm run build

OPNSenseMCP/ ├── src/ # Source code │ ├── api/ # API client │ ├── resources/ # Resource implementations │ └── index.ts # MCP server entry ├── docs/ # Documentation ├── scripts/ # Utility scripts │ ├── test/ # Test scripts │ ├── debug/ # Debug utilities │ └── fixes/ # Fix scripts └── dist/ # Build output

Contributions are welcome! Please seeCONTRIBUTING.mdfor guidelines.

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

- Issues:GitHub Issues
- Discussions:GitHub Discussions
- Documentation:Full Documentation

- Built for use withAnthropic's Claude
- Implements theModel Context Protocol
- Designed forOPNsensefirewall

A server for real-time network packet monitoring and security analysis.