OPNsense 路由器管理 MCP 服务器

OPNsense MCP Server

A hosted Model Context Protocol server that gives Claude (and other MCP clients) full access to your OPNsense router's API. Connects Claude.ai to your firewall, diagnostics, VPN, DNS, DHCP, and 20+ other OPNsense modules via a single MCP integration.

Inspired by Pixelworlds/opnsense-mcp-server, rebuilt from scratch with a focus on reliability and Claude.ai hosted MCP support.

Features

• 24 core tool modules covering firewall, diagnostics, interfaces, VPN (WireGuard/OpenVPN/IPsec), DNS, DHCP, and more
• 750+ methods auto-discovered from the OPNsense TypeScript SDK with per-method parameter introspection
• OAuth 2.0 + PKCE for secure authentication from Claude.ai
• Retry with backoff on transient API failures (5xx, timeouts, connection resets)
• Structured logging with timestamps and component tags
• Graceful shutdown on SIGTERM/SIGINT
• Optional plugin support — enable INCLUDE_PLUGINS=true to expose 60+ additional plugin modules

Architecture

Claude.ai → Cloudflare Tunnel → MCP Server (Node.js) → OPNsense API
                                     ↑
                              OAuth 2.0 bearer token

The server runs natively on your LAN (not in Docker) so it can reach the OPNsense router directly. A Cloudflare Tunnel (or similar reverse proxy) exposes it to Claude.ai.

Quick start

1. Create an OPNsense API key

In your OPNsense web UI: System > Access > Users > edit your user > API keys > +

2. Configure

cp .env.example .env
# Edit .env with your API key, secret, OAuth password, and public URL

3. Build and run

npm install
npm run build
npm start

4. Connect Claude.ai

Add the MCP server in Claude.ai settings using your public URL (e.g. https://opnsense-mcp.yourdomain.com). Claude will redirect to the OAuth flow — enter the password you set in OAUTH_PASSWORD.

Running as a service (macOS)

Create a launchd plist at ~/Library/LaunchAgents/com.opnsense-mcp.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.opnsense-mcp</string>
    <key>WorkingDirectory</key>
    <string>/path/to/opnsense-mcp</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/node</string>
        <string>/path/to/opnsense-mcp/dist/server.js</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardErrorPath</key>
    <string>/path/to/opnsense-mcp/logs/stderr.log</string>
</dict>
</plist>

Then load it:

mkdir -p logs
launchctl load ~/Library/LaunchAgents/com.opnsense-mcp.plist

Environment variables

Available tools

Each tool exposes all methods from the corresponding OPNsense API module:

With INCLUDE_PLUGINS=true, 60+ additional plugin modules are available (HAProxy, Caddy, Tailscale, CrowdSec, etc.).

Project structure

src/
  config.ts    — Environment validation
  logger.ts    — Structured logging
  tools.ts     — Tool discovery, parameter introspection, retry logic
  oauth.ts     — OAuth 2.0 with PKCE
  server.ts    — Express app, MCP transport, graceful shutdown

License

MIT