Labsco
vespo92 logo

OPNSense MCP Server

★ 61

from vespo92

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

🔥🔥🔥✓ VerifiedAccount requiredNeeds API keys
#automation#git

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

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 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 Tools

  • 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

Network Tools

  • 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 Tools

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

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

Documentation

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

Support