OPNSenseMCP

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+ to run the server (Bun 1.1.39+ to develop on it)
• OPNsense firewall (v24.7+ recommended)
• API credentials for OPNsense
• SSH access (optional, for advanced features)

Quick Start with npm

1. Install the package: bash npm install -g opnsense-mcp-server
2. Create a .env file with your credentials: `bash # 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

Recommended for a new/production router — see "Safety Modes" below

OPNSENSE_READ_ONLY=true

3. Start the MCP server:
```bash
opnsense-mcp-server

⚠️ Safety Modes (read this before pointing at a production router)

By default this server can make live, immediate changes to your firewall — add/delete rules, change NAT, restart services, run whitelisted shell commands over SSH. Two environment variables (operator-only — a tool call can never set or override them) add a safety net:

Both are enforced at the two lowest-level chokepoints this server uses to reach the router — the API client and the SSH executor — so they apply uniformly across all 140+ tools, not on a per-tool basis. If both are set, OPNSENSE_READ_ONLY wins.

# First time pointing this at a real router? Start here:
OPNSENSE_READ_ONLY=true

# Once you trust it, watch what it would do before going live:
OPNSENSE_DRY_RUN=true

# Remove both once you're confident.

See CONFIGURATION.md for the config reference, or docs/features/safety-modes.md for how it works under the hood.

Quick Start with Bun (Faster)

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

Production

bun run start:bun

### Using Bun with Claude Desktop

```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):

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

• Quick Start Guide
• Configuration Guide
• NAT Management
• SSH/CLI Execution
• Firewall Rules
• Safety Modes (Dry-Run & Read-Only)
• Troubleshooting

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

This repo uses Bun as its development toolchain (install, build, tests). The published package is still plain Node — it is consumed as node dist/index.js — so Bun is only needed to work on the project, not to run it.

git clone https://github.com/vespo92/OPNSenseMCP.git
cd OPNSenseMCP
bun install
bun run build
bun run test

The lockfile is bun.lock; there is no package-lock.json. CI runs bun install --frozen-lockfile, so commit bun.lock alongside any package.json change.

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