OPNsense MCP Server

![npm version](https://www.npmjs.com/package/opnsense-mcp-server) ![License: MIT](https://opensource.org/licenses/MIT)

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

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 .env file (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 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

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

OPNSenseMCP