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
• HashiCorp Vault Integration (Optional)
• 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

HashiCorp Vault Integration (Optional)

mcp-opnsense supports opportunistic AppRole authentication against a HashiCorp Vault instance. When Vault env vars are present, the server fetches OPNsense credentials from KV v2 at startup. If they are absent, the server falls back silently to direct env vars or MCP_SECRETS_FILE — no configuration change or restart required.

How It Works

1. At startup, the server checks for NAS_VAULT_ADDR in process.env.
2. If set, it authenticates via AppRole (NAS_VAULT_ROLE_ID + NAS_VAULT_SECRET_ID), reads the secret at <NAS_VAULT_KV_MOUNT>/data/<path>, and maps the KV fields to OPNsense env vars.
3. If NAS_VAULT_ADDR is not set (or any Vault call fails), a single warning line is written to stderr and the server continues with whatever env vars are already available.
4. The Vault client uses the global fetch built into Node 20+ — no additional runtime dependencies are added.

Secret Precedence

Explicit env vars  >  Vault  >  MCP_SECRETS_FILE  >  error (required var missing)

• Values already present in process.env are never overwritten by Vault.
• Vault is skipped entirely if NAS_VAULT_ADDR is unset.
• MCP_SECRETS_FILE is the last fallback (see Loading Secrets from a File below).

Vault Environment Variables

... View full README on GitHub