OPNSense MCP Server

What is OPNSense MCP Server about?

Enables control of OPNsense firewalls using natural‑language instructions. The server translates Claude Desktop or Claude Code queries into OPNsense API calls, handling VLANs, rules, device lookup, DNS filtering, HAProxy, and IaC deployments.

How to use OPNSense MCP Server?

Installation – Run the server with NPX (no global install required):
```
npx opnsense-mcp-server
```
or install globally with npm i -g opnsense-mcp-server.
Add to Claude configuration – Insert an MCP entry in claude_desktop_config.json (macOS, Windows, Linux) or .claude/config.json for Claude Code. Use the NPX command and provide the required environment variables (OPNSENSE_HOST, OPNSENSE_API_KEY, OPNSENSE_API_SECRET, optional OPNSENSE_VERIFY_SSL).
Start interacting – Launch Claude Desktop/Code and issue natural‑language commands such as “Create a guest network on VLAN 50” or “Block social media sites”. The server processes the request and applies the changes via the OPNsense API.

Key Features

Network Management – Create/manage VLANs, interfaces, and firewall rules.
Device Discovery – Query ARP tables, DHCP leases, and perform network scans.
DNS Filtering – Block domains or whole categories.
HAProxy Configuration – Set up load balancing and reverse proxy rules.
Infrastructure as Code – Declarative deployment of complete network setups.
Backup & Restore – Export and import OPNsense configuration snapshots.
Dual Transport – Works directly with Claude Desktop or as a standalone HTTP server.
Caching & Logging – Optional response caching and adjustable log levels.

Use Cases

Quickly provision a secure guest Wi‑Fi network.
Enforce content filters (e.g., block gambling or adult sites) without manual rule editing.
Discover all devices on the network for inventory or security audits.
Deploy HAProxy load‑balancing for web services using a single chat command.
Automate backup of firewall configuration before major changes.

FAQ

Q: Do I need to install anything on the OPNsense appliance? A: Only enable the built‑in API (System → Settings → Administration → Enable API) and create an API user with appropriate privileges.

Q: Can I store API credentials securely? A: Yes. Use the system keychain syntax {{keychain:opnsense-api-key}} in the MCP configuration to pull secrets from macOS Keychain, Windows Credential Manager, or Linux Secret Service.

Q: What Node.js version is required? A: Node 18 or newer.

Q: How do I run the server in HTTP mode for automation? A: Execute npm run start:sse (default port 3000) and point your automation tools to http://localhost:3000.

Q: What if Claude cannot connect to the server? A: Verify the NPX command path, ensure all environment variables are set correctly (host must include https://), and test the server manually via npx 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

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

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

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

OPNSense MCP Server