OPNsense MCP Server

Local setup required. This server has to be cloned and prepared on your machine before you register it in Claude Code.
1

Set the server up locally

Run this once to clone and prepare the server before adding it to Claude Code.

Run in terminal
npm install
cp .env.example .env
npm run build
node dist/index.js
2

Register it in Claude Code

After the local setup is done, run this command to point Claude Code at the built server.

Run in terminal
claude mcp add -e "OPNSENSE_URL=${OPNSENSE_URL}" -e "OPNSENSE_API_KEY=${OPNSENSE_API_KEY}" -e "OPNSENSE_API_SECRET=${OPNSENSE_API_SECRET}" mcp-opnsense -- node "<FULL_PATH_TO_MCP_OPNSENSE>/dist/index.js"

Replace <FULL_PATH_TO_MCP_OPNSENSE>/dist/index.js with the actual folder you prepared in step 1.

Required:OPNSENSE_URLOPNSENSE_API_KEYOPNSENSE_API_SECRET+ 2 optional
README.md

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

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.

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

Variable Required Default Description
OPNSENSE_URL Yes — OPNsense base URL (e.g. https://192.168.1.1)
OPNSENSE_API_KEY Yes — API key for authentication
OPNSENSE_API_SECRET Yes — API secret for authentication
OPNSENSE_VERIFY_SSL No true Set to false for self-signed certificates
OPNSENSE_TIMEOUT No 30000 Request timeout in milliseconds

Available Tools (62)

DNS/Unbound (12 tools)

Tool Description
opnsense_dns_list_overrides List host overrides (A/AAAA/CNAME)
opnsense_dns_add_override Add a host override record
opnsense_dns_delete_override Delete a host override by UUID
opnsense_dns_list_forwards List DNS-over-TLS forwarding servers
opnsense_dns_add_forward Add a DNS forwarding server
opnsense_dns_delete_forward Delete a DNS forward by UUID
opnsense_dns_list_blocklist List domain overrides (blocked domains)
opnsense_dns_block_domain Block a domain
opnsense_dns_unblock_domain Unblock a domain by UUID
opnsense_dns_flush_cache Flush DNS cache and DNSBL data
opnsense_dns_diagnostics Dump DNS cache for diagnostics
opnsense_dns_apply Apply DNS changes (reconfigure Unbound)

Firewall (8 tools)

Tool Description
opnsense_fw_list_rules List all firewall filter rules
opnsense_fw_add_rule Create a firewall rule
opnsense_fw_update_rule Update a firewall rule by UUID
opnsense_fw_delete_rule Delete a firewall rule by UUID
opnsense_fw_toggle_rule Enable/disable a firewall rule
opnsense_fw_list_aliases List firewall aliases (host, network, port, URL)
opnsense_fw_manage_alias Create/update/delete aliases
opnsense_fw_apply Apply pending firewall changes

Diagnostics (8 tools)

Tool Description
opnsense_diag_arp_table Show ARP table (IP-to-MAC mappings)
opnsense_diag_routes Show routing table
opnsense_diag_ping Ping a host from OPNsense
opnsense_diag_traceroute Traceroute to a destination
opnsense_diag_dns_lookup Perform DNS lookup from OPNsense
`opnsense_diag_f

Tools (7)

opnsense_dns_list_overridesList host overrides (A/AAAA/CNAME)
opnsense_dns_add_overrideAdd a host override record
opnsense_dns_delete_overrideDelete a host override by UUID
opnsense_fw_list_rulesList all firewall filter rules
opnsense_fw_add_ruleCreate a firewall rule
opnsense_diag_pingPing a host from OPNsense
opnsense_diag_tracerouteTraceroute to a destination

Environment Variables

OPNSENSE_URLrequiredOPNsense base URL
OPNSENSE_API_KEYrequiredAPI key for authentication
OPNSENSE_API_SECRETrequiredAPI secret for authentication
OPNSENSE_VERIFY_SSLSet to false for self-signed certificates
OPNSENSE_TIMEOUTRequest timeout in milliseconds

Configuration

claude_desktop_config.json
{"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"}}}}

Try it

→List all current firewall rules and identify any that are disabled.
→Ping 8.8.8.8 from the OPNsense firewall to check connectivity.
→Add a new host override for 'internal.server' pointing to 192.168.1.50.
→Show me the current ARP table to see connected devices.
→Flush the DNS cache on the firewall.

Frequently Asked Questions

What are the key features of OPNsense MCP Server?

Manage DNS/Unbound settings including host overrides and blocklists.. Control firewall rules, aliases, and NAT configurations.. Perform network diagnostics like ping, traceroute, and DNS lookups.. Manage DHCP leases and static mappings for ISC and Kea.. Handle system backups, certificate management, and firmware plugins..

What can I use OPNsense MCP Server for?

Automating firewall rule updates during deployment workflows.. Quickly troubleshooting network connectivity issues from the firewall perspective.. Managing DNS host overrides programmatically across multiple OPNsense instances.. Auditing firewall configurations and active leases via natural language queries..

How do I install OPNsense MCP Server?

Install OPNsense MCP Server by running: npm install && cp .env.example .env && npm run build && node dist/index.js

What MCP clients work with OPNsense MCP Server?

OPNsense MCP Server works with any MCP-compatible client including Claude Desktop, Claude Code, Cursor, and other editors with MCP support.

Turn this server into reusable context

Keep OPNsense MCP Server docs, env vars, and workflow notes in Conare so your agent carries them across sessions.

Need the old visual installer? Open Conare IDE.
Open Conare
View all monitoring servers →

Related MCP Servers

Skylos
Find dead code, secrets, and exploitable flows in Python, TypeScript, and Go.
monitoring344 stars
Linux MCP Server
Read-only Linux system administration and diagnostics on RHEL-based systems.
monitoring189 stars
Charles MCP Server
Integrates Charles Proxy with MCP clients for real-time network traffic analysis
monitoring118 stars
HomeButler
All-in-one homelab management MCP server.
monitoring64 stars
Wireshark MCP
Give your AI assistant a packet analyzer.
monitoring55 stars
RenderDoc MCP
Analyze GPU frame captures for graphics debugging and performance analysis.
monitoring42 stars