Model Context Protocol server for OPNSense firewall management with inter-VLAN routing diagnostics, ARP table, DNS filtering and HAProxy support via Claude Desktop
npm install 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.
1. Install the package:
``bash`
npm install -g opnsense-mcp-server
2. Create a .env file with your credentials:`bashRequired
OPNSENSE_HOST=https://your-opnsense-host:port
OPNSENSE_API_KEY=your-api-key
OPNSENSE_API_SECRET=your-api-secret
OPNSENSE_VERIFY_SSL=false
3. Start the MCP server:
`bash
opnsense-mcp-server
`$3
Bun provides significantly faster startup times and better performance.
1. Install Bun (if not already installed):
`bash
curl -fsSL https://bun.sh/install | bash
`2. Clone and install:
`bash
git clone https://github.com/vespo92/OPNSenseMCP.git
cd OPNSenseMCP
bun install
`3. Create your
.env file (same as npm version above)4. Run with Bun:
`bash
Development with hot reload
bun run dev:bunProduction
bun run start:bun
`$3
`json
{
"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):`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
$3
`javascript
// Automatically fix DMZ to LAN routing
await mcp.call('nat_fix_dmz', {
dmzNetwork: '10.0.6.0/24',
lanNetwork: '10.0.0.0/24'
});
`$3
`javascript
// 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'
});
`$3
`javascript
// Run comprehensive routing diagnostics
await mcp.call('routing_diagnostics', {
sourceNetwork: '10.0.6.0/24',
destNetwork: '10.0.0.0/24'
});
`$3
`javascript
// 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:
$3
- 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$3
- 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$3
- 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$3
- system_execute_command - Execute CLI command
- backup_create - Create configuration backup
- service_restart - Restart a serviceFor 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:
`bash
Test NAT functionality
npx tsx scripts/test/test-nat-ssh.tsTest firewall rules
npx tsx scripts/test/test-rules.tsTest routing diagnostics
npx tsx scripts/test/test-routing.tsRun all tests
npm test
`Development
$3
`bash
git clone https://github.com/vespo92/OPNSenseMCP.git
cd OPNSenseMCP
npm install
npm run build
`$3
`
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
$3
- Verify API key and secret are correct
- Ensure API access is enabled in OPNsense
- Check firewall rules allow API access$3
- Verify SSH credentials in .env
- Ensure SSH is enabled on OPNsense
- Check user has appropriate privileges$3
- NAT management requires SSH access
- Add SSH credentials to environment variables
- Test with: npx tsx scripts/test/test-nat-ssh.ts`Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
This project is licensed under the MIT License - see the LICENSE file for details.
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: Full Documentation
- 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