Skip to main content
Glama

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

  1. Install the package:
npm install -g opnsense-mcp-server
  1. Create a .env file 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
  1. Start the MCP server:
opnsense-mcp-server

Usage with Claude Desktop

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

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

Acknowledgments


Version: 0.8.2 | Status: Production Ready | Last Updated: August 2025

Related MCP Servers

  • A
    security
    A
    license
    A
    quality
    Lets you use Claude Desktop, or any MCP Client, to use natural language to accomplish things on your Cloudflare account.
    Last updated -
    2
    1,159
    2,918
    Apache 2.0
    • Apple
  • A
    security
    A
    license
    A
    quality
    Enables natural language interaction with Azure services through Claude Desktop, supporting resource management, subscription handling, and tenant selection with secure authentication.
    Last updated -
    9
    4
    15
    MIT License
  • -
    security
    A
    license
    -
    quality
    A 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 -
    14
    MIT License
  • -
    security
    F
    license
    -
    quality
    Provides 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 -
    • Linux
    • Apple

View all related MCP servers

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/vespo92/OPNSenseMCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server