mcp-opnsense

Slim OPNsense MCP Server for managing firewall infrastructure via the OPNsense REST API.

No SSH. No shell execution. API-only. 3 runtime dependencies.

Table of Contents

• Features
• Quick Start
• Claude Code Integration
• Environment Variables
• Available Tools (62)
• Claude Code Skills
• Known Limitations
• Security
• Development
• License

Features

62 tools across 8 domains:

• DNS/Unbound (12) — Host overrides, forwards, blocklist, cache management
• Firewall (8) — Rules, aliases, NAT, apply changes
• Diagnostics (8) — ARP, routes, ping, traceroute, DNS lookup, firewall states/logs
• Interfaces (3) — List, configuration, statistics (read-only)
• DHCP (5) — Leases, static mappings (ISC DHCPv4 + Kea dual support)
• System (7) — Info, backup (list/download/revert), certificate listing, service control
• ACME/Let's Encrypt (14) — Accounts, challenges, certificates, renewal, settings
• Firmware/Plugins (5) — Version info, plugin management

Quick Start

npm install
cp .env.example .env   # Edit with your OPNsense API credentials
npm run build
node dist/index.js     # stdio transport for MCP

Claude Code Integration

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "opnsense": {
      "command": "node",
      "args": ["/path/to/mcp-opnsense/dist/index.js"],
      "env": {
        "OPNSENSE_URL": "https://your-opnsense.example.com",
        "OPNSENSE_API_KEY": "your-api-key",
        "OPNSENSE_API_SECRET": "your-api-secret",
        "OPNSENSE_VERIFY_SSL": "true"
      }
    }
  }
}

Environment Variables

Available Tools (62)

DNS/Unbound (12 tools)

Firewall (8 tools)

Diagnostics (8 tools)

Interfaces (3 tools, read-only)

DHCP (5 tools)

System (7 tools)

ACME/Let's Encrypt (14 tools)

Firmware/Plugins (5 tools)

Skills

Claude Code skills compose MCP tools into higher-level workflows. See .claude/skills/README.md for detailed documentation.

Known Limitations

Some OPNsense operations are not available via the REST API and require manual GUI access:

• Web GUI SSL certificate assignment — ssl-certref can only be changed via System > Settings > Administration in the web UI. See docs/manual-operations.md.
• Configuration upload/import — OPNsense has no API to upload configuration XML files. Use opnsense_sys_backup_revert to revert to local backups, or upload via the web GUI.
• User/group management — Not exposed via REST API.
• VPN configuration — Limited API coverage; most settings require the web UI.

Security

• Transport: stdio only — no HTTP endpoints exposed
• Authentication: OPNsense API key/secret via environment variables
• SSL: Enabled by default, configurable for self-signed certs
• No SSH: All operations use the OPNsense REST API exclusively
• Input validation: Strict Zod schemas for all tool parameters
• Destructive operations: Require explicit confirm: true parameter
• See SECURITY.md for the full security policy

Development

npm test          # Run unit tests (vitest)
npm run build     # Compile TypeScript
npx tsc --noEmit  # Type check only

See CONTRIBUTING.md for contribution guidelines.

License

This project is dual-licensed:

• Open Source: GNU Affero General Public License v3.0 (AGPL-3.0) — free for open-source and non-commercial use
• Commercial: Available for proprietary integrations — see COMMERCIAL_LICENSE.md

If you use mcp-opnsense in a proprietary product or SaaS offering, a commercial license is required. Support development by sponsoring us on GitHub.