OPNsense MCP Server

A secure Model Context Protocol (MCP) server for managing OPNsense firewalls through AI assistants like Claude Code, Cursor, and other MCP-compatible tools.

81 tools across 10 domains: system, firewall, network, DNS, DHCP, VPN, HAProxy, services, diagnostics, and security.

Security Model

This MCP server is designed with security as the primary concern:

• Read-only by default — write operations require explicit opt-in via OPNSENSE_ALLOW_WRITES=true
• Savepoint/rollback — all firewall modifications use OPNsense's built-in 60-second auto-revert mechanism; changes must be explicitly confirmed or they roll back automatically
• Endpoint blocklist — dangerous endpoints (halt, reboot, poweroff, firmware update/upgrade) are hard-blocked at the API client level and can never be called
• API-only — no SSH access, no command execution, no direct config file manipulation
• Local transport — STDIO only, no network-exposed HTTP/SSE endpoints
• No credential exposure — API keys are never included in tool output, logs, or error messages
• Input validation — hostname parameters are validated against shell metacharacter injection
• Sensitive data stripping — config backup strips passwords and keys by default

Available Tools (81)

System (7 tools)

Network (5 tools)

Firewall (21 tools)

DNS (13 tools)

DHCP (8 tools)

VPN (3 tools)

HAProxy (8 tools)

Full configuration management for the HAProxy load balancer (requires os-haproxy plugin).

Note: HAProxy changes do NOT use savepoint protection — they apply immediately on reconfigure. Always call opn_haproxy_configtest before opn_reconfigure_haproxy.

Services (11 tools)

Diagnostics (4 tools)

Security (1 tool)

Write Operations and Savepoints

Write operations require OPNSENSE_ALLOW_WRITES=true and use OPNsense's savepoint mechanism for safety:

1. Before any firewall change, a savepoint is created automatically
2. The change is applied (rule toggle, add, or delete)
3. A 60-second countdown starts — if not confirmed, OPNsense automatically reverts the change
4. Use opn_confirm_changes with the returned revision to make changes permanent

This means if an AI assistant makes a bad firewall change that locks you out, the change will automatically revert within 60 seconds.

Note: opn_reconfigure_unbound, opn_reconfigure_haproxy, opn_reconfigure_ddclient, opn_reconfigure_dnsmasq, and opn_configure_mdns_repeater require writes but don't use savepoints — they apply service configuration changes and are not automatically revertible.

IPv6 Support

Fully Automated via MCP

• IPv6 Firewall Rules — Create rules with ip_protocol="inet6" (savepoint-protected)
• HAProxy IPv6 Bindings — Frontends with [::]:443 or [2001:db8::1]:443 bind addresses
• HAProxy IPv6 Backends — Servers with IPv6 addresses, resolvePrefer: ipv6 on backends
• Dynamic DNS with IPv6 — DDNS accounts with IPv6-capable checkip methods
• DHCPv6 Ranges (dnsmasq) — IPv6 DHCP ranges with Router Advertisement configuration
• DNS AAAA Records — Unbound host overrides with IPv6 addresses
• IPv6 Diagnostics — Traceroute with ip_version="6", ping via hostname

Requires Manual GUI Configuration

These settings lack MVC API support in OPNsense and must be configured via the web GUI:

• WAN IPv6 setup — PPPoE with DHCPv6 prefix delegation, static IPv6, SLAAC
• LAN IPv6 addressing — Track Interface mode, static /64 assignment, prefix ID
• Interface assignment — Assigning physical ports to WAN/LAN/OPT roles
• 6to4/6rd tunnels — Transition tunnel mechanisms

Known Limitations

• ISC DHCP / Kea DHCPv6: Not implemented. Only dnsmasq (the modern default) is supported for DHCPv6 ranges and Router Advertisements. ISC DHCP is deprecated; Kea DHCPv6 lease visibility is limited in the API.
• radvd: Not implemented as a separate tool set. Dnsmasq handles Router Advertisements natively via range configuration. Only one RA daemon should run per interface.
• Dual-stack firewall rules: inet46 (dual-stack) works correctly in MVC API rules (opn_add_firewall_rule). However, inet46 in legacy XML filter rules (GUI) silently produces no PF output — this is a known OPNsense bug that only affects legacy rules.
• Legacy GUI rules: Firewall rules created via the traditional OPNsense GUI are not accessible through the MVC API. Use opn_get_config_section("filter") for read-only access.

Recommended IPv6 Migration Workflow

1. Manual (GUI): Configure WAN IPv6 (DHCPv6-PD from ISP or static)
2. Manual (GUI): Configure LAN interfaces (Track Interface mode for prefix delegation)
3. MCP: Configure Router Advertisements via opn_add_dnsmasq_range with RA flags
4. MCP: Create IPv6 firewall rules (ICMPv6 must be allowed for NDP/RA/PMTUD)
5. MCP: Add IPv6 DNS records via opn_add_dns_override
6. MCP: Configure Dynamic DNS with IPv6 checkip method
7. MCP: Add IPv6 bind addresses to HAProxy frontends
8. MCP: Verify with opn_ping, opn_traceroute (ip_version="6"), opn_gateway_status

Version Compatibility

The server automatically detects the OPNsense version on first connection and selects the correct API endpoint naming convention (camelCase for pre-25.7, snake_case for 25.7+).

Note on firewall rules: opn_list_firewall_rules shows rules managed via the MVC/automation API. Rules configured through the OPNsense GUI use a legacy format not accessible via this API. This is a known OPNsense limitation.

Development

# Clone and install dev dependencies
git clone https://github.com/lucamarien/opnsense-mcp-server
cd opnsense-mcp-server
pip install -e ".[dev]"

# Run all tests (no real OPNsense needed — all tests use mocked API)
pytest -v

# Full CI pipeline (lint, format, type check, security scan, tests)
make validate

# Individual checks
ruff check src/ tests/          # Lint (includes bandit security checks)
ruff format src/ tests/          # Format
mypy src/ --strict               # Type checking

Best Practices

Domain-specific guides for common firewall configuration tasks:

• WhatsApp Calling Firewall Rules — Allow WhatsApp voice/video calls through a default-deny firewall using URL table aliases and scoped rules

These guides show real-world MCP tool usage patterns and explain the security considerations behind each approach.

Contributing

See CONTRIBUTING.md for detailed guidelines. Key points:

1. All tests must use mocked API responses — never connect to a real OPNsense
2. No overlapping tools — each tool must have a distinct purpose
3. Write clear docstrings — they're the AI's only guide to tool selection
4. Return structured data (dicts), not formatted strings
5. Run make validate before submitting

License

MIT

Requirements

• Python 3.11+
• OPNsense 24.7 or newer — the MCP server relies on the MVC-based API endpoints introduced in OPNsense 24.7. Older versions use a different API structure that is not compatible. The server auto-detects the OPNsense version on first connect and selects the correct endpoint naming (camelCase for pre-25.7, snake_case for 25.7+). OPNsense 26.x is fully supported, including its changed firmware status response format.

Quick Start

1. Create an OPNsense API Key

1. Log in to your OPNsense web interface
2. Go to System > Access > Users
3. Either edit an existing user or create a dedicated API user:
   • For production use, create a dedicated user (e.g., mcp-api) with only the privileges needed
   • For read-only access, assign the user to a group with read-only API access
4. Scroll down to the API keys section and click the + button
5. A key/secret pair will be generated and a file (apikey.txt) will be downloaded
6. The file contains two lines — key=your-api-key-here and secret=your-api-secret-here
7. Store these credentials securely — the secret cannot be retrieved again from OPNsense

Tip: For a read-only setup (recommended for getting started), you don't need to change any permissions — the default API access is sufficient for all read-only tools.

2. Install

# Using pip
pip install opnsense-mcp-server

# Using uv (recommended for isolated environments)
uv pip install opnsense-mcp-server

# Using Docker
docker pull lucamarien/opnsense-mcp-server

# From source
git clone https://github.com/lucamarien/opnsense-mcp-server
cd opnsense-mcp-server
pip install -e .

3. Configure Your AI Assistant

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "opnsense": {
      "command": "opnsense-mcp",
      "env": {
        "OPNSENSE_URL": "https://192.168.1.1/api",
        "OPNSENSE_API_KEY": "your-api-key-here",
        "OPNSENSE_API_SECRET": "your-api-secret-here",
        "OPNSENSE_VERIFY_SSL": "false",
        "OPNSENSE_ALLOW_WRITES": "false"
      }
    }
  }
}

Alternative: Use "command": "python", "args": ["-m", "opnsense_mcp"] if the opnsense-mcp CLI is not on your PATH.

Or add it globally to ~/.claude/claude_code_config.json.

Claude Code (Docker)

{
  "mcpServers": {
    "opnsense": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "OPNSENSE_URL=https://192.168.1.1/api",
        "-e", "OPNSENSE_API_KEY=your-api-key-here",
        "-e", "OPNSENSE_API_SECRET=your-api-secret-here",
        "-e", "OPNSENSE_VERIFY_SSL=false",
        "-e", "OPNSENSE_ALLOW_WRITES=false",
        "lucamarien/opnsense-mcp-server"
      ]
    }
  }
}

Cursor

Add to your Cursor MCP settings (Settings > MCP):

{
  "mcpServers": {
    "opnsense": {
      "command": "opnsense-mcp",
      "env": {
        "OPNSENSE_URL": "https://192.168.1.1/api",
        "OPNSENSE_API_KEY": "your-api-key-here",
        "OPNSENSE_API_SECRET": "your-api-secret-here",
        "OPNSENSE_VERIFY_SSL": "false"
      }
    }
  }
}

Configuration

Custom ports: If your OPNsense web GUI runs on a non-standard port (e.g., 10443), include it in the URL: https://192.168.1.1:10443/api

Troubleshooting

Connection Issues

"Connection refused" or timeout errors

• Verify OPNSENSE_URL ends with /api (e.g., https://192.168.1.1/api)
• If using a non-standard port, include it: https://192.168.1.1:10443/api
• Ensure the OPNsense web GUI is accessible from the machine running the MCP server

SSL certificate errors

• For self-signed certificates (default OPNsense setup), set OPNSENSE_VERIFY_SSL=false
• For production, install a proper certificate on OPNsense and keep OPNSENSE_VERIFY_SSL=true

Authentication Issues

401 Unauthorized

• Verify OPNSENSE_API_KEY and OPNSENSE_API_SECRET are correct
• API keys are case-sensitive — copy them exactly from the downloaded apikey.txt
• Check that the API user is not disabled in OPNsense
• Verify the API user has sufficient privileges for the operations you're attempting

403 Forbidden

• The API user may lack permissions for the requested endpoint
• For write operations, ensure OPNSENSE_ALLOW_WRITES=true is set

Tool-Specific Issues

opn_list_firewall_rules returns empty results

• This tool only shows MVC/automation rules, not legacy GUI rules
• Create rules via the automation API or opn_add_firewall_rule to see them

opn_ping times out

• The firewall may not have a route to the target host
• Check gateway status with opn_gateway_status
• Default timeout is 30 seconds (30 poll cycles)

opn_download_config shows [REDACTED] values

• This is the default behavior for security. Pass include_sensitive=true to include passwords and keys (use with caution in AI conversations)

Write operations fail with "writes not enabled"

• Set OPNSENSE_ALLOW_WRITES=true in your MCP server configuration
• This is intentionally disabled by default for safety

Savepoint confirmation fails

• The revision parameter must match exactly what was returned by the write operation
• Confirmations must happen within 60 seconds or the change auto-reverts

Diagnostic Commands

If you need to debug the MCP server:

# Test API connectivity directly
curl -k -u "your-key:your-secret" https://your-opnsense-ip/api/core/firmware/status

# Run the server directly
python -m opnsense_mcp

# Run tests to verify installation
pytest -v