OPNSense MCP 服务器 | Awesome MCP Servers

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

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

# Recommended for a new/production router — see "Safety Modes" below
# OPNSENSE_READ_ONLY=true

Start the MCP server:

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:

Variable	Effect
`OPNSENSE_READ_ONLY=true`	Every mutating API call and every non-read-only SSH command is rejected before it's sent. Write-capable tools are also hidden from the tool list, so the model never sees them as an option.
`OPNSENSE_DRY_RUN=true`	Mutating calls are simulated instead of sent — you get a log line and a synthetic success response describing what would have happened, with no request reaching the router.

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.

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

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

OPNSense MCP Server

文档