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+ or Bun 1.0+
- OPNsense firewall (v24.7+ recommended)
- API credentials for OPNsense
- SSH access (optional, for advanced features)
Quick Start with npm
- Install the package:
npm install -g opnsense-mcp-server
- 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
- Start the MCP server:
opnsense-mcp-server
Quick Start with Bun (Faster)
Bun provides significantly faster startup times and better performance.
- Install Bun (if not already installed):
curl -fsSL https://bun.sh/install | bash
- Clone and install:
git clone https://github.com/vespo92/OPNSenseMCP.git
cd OPNSenseMCP
bun install
-
Create your
.envfile (same as npm version above) -
Run with Bun:
# Development with hot reload
bun run dev:bun
# Production
bun run start:bun
Using Bun with Claude Desktop
{
"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"
}
}
}
}
Usage with Claude Desktop (npm)
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"
}
}
}
}
Common Use Cases
Fix DMZ NAT Issues
// Automatically fix DMZ to LAN routing
await mcp.call('nat_fix_dmz', {
dmzNetwork: '10.0.6.0/24',
lanNetwork: '10.0.0.0/24'
});
Create Firewall Rules
// 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'
});
Diagnose Routing Issues
// Run comprehensive routing diagnostics
await mcp.call('routing_diagnostics', {
sourceNetwork: '10.0.6.0/24',
destNetwork: '10.0.0.0/24'
});
Execute CLI Commands
// Run any OPNsense CLI command
await mcp.call('system_execute_command', {
command: 'pfctl -s state | grep 10.0.6'
});
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
- Quick Start Guide
- Configuration Guide
- NAT Management
- SSH/CLI Execution
- Firewall Rules
- Troubleshooting
Testing
The repository includes comprehensive testing utilities:
# 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
Development
Building from Source
git clone https://github.com/vespo92/OPNSenseMCP.git
cd OPNSenseMCP
npm install
npm run build
Project Structure
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
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