auth_manage
Authentication management - 19 available methods including: groupAdd, groupDel, groupGet, groupSet, privGet...
LABSCO SUMMARY
A firewall's entire API fits in your context as 24 definitions instead of hundreds.
Because the method list stays out of the tool schema, adding this server costs a fixed and small amount of context no matter how much of OPNsense you end up using. The bill comes due at call time: the descriptions name only the first few methods per subsystem, so any other method name has to come from OPNsense's own API reference before you can invoke it.
What it is
A thin wrapper over the OPNsense API arranged as one tool per subsystem: 24 tools, each taking a method and params.
What you get
- Firewall work on one dispatcher, including alias item add and delete and GeoIP alias reads
- Interfaces and routing across three subsystems: interface, route and routing methods
- Address assignment spread over DHCPv4, DHCPv6, DHCP relay, Kea and dnsmasq
- VPN in all three flavours — IPsec, OpenVPN and WireGuard, one dispatcher each
- Live state and monitoring: diagnostics from CPU usage streams to reverse DNS lookups, plus Monit service checks and syslog
- Security and trust: IDS methods including alert queries, trust methods for certificate authorities, captive portal and authentication
- Housekeeping through the core module, which covers backups, and the firmware module, which covers audit, changelog and check
Requirements
An OPNsense URL with an API key and secret, and npx on your PATH. Each call also needs the exact method name for its subsystem; the tool descriptions name the first five of each.
Setup effort
One command plus a key — npm install -g @richard-stovall/opnsense-mcp-server, then supply credentials
USE CASES
01
Auditing firmware before a maintenance window
One subsystem covers the whole firmware question — audit, changelog, check — so what is pending and what it changes are read before anything is applied.
02
Reading the box's live state during an incident
Diagnostics runs from CPU usage streams to reverse DNS lookups, and Monit reports what the service checks are saying — between them they answer whether the problem is load, a service, or the network.
03
Editing firewall aliases without opening the web UI
Alias item add and delete, alias reads and GeoIP aliases are all methods on one dispatch tool, so a change to an address group is a single call with the method name and its params.
04
Bringing up a VPN peer
Each VPN technology has its own dispatcher, so the client-add method you need depends on which one the peer speaks — WireGuard, OpenVPN or IPsec.
05
Taking a configuration backup
Backups live with the rest of core system management: list them, diff two of them, download one, and see which providers are configured — all through the same tool with a different method.
24 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
captiveportal_manage
Captiveportal management - 27 available methods including: accessApi, accessLogoff, accessLogon, serviceDelTemplate, serviceGetTemplate...
core_manage
Core system management - 46 available methods including: backupBackups, backupDeleteBackup, backupDiff, backupDownload, backupProviders...
cron_manage
Cron management - 8 available methods including: serviceReconfigure, settingsAddJob, settingsDelJob, settingsGet, settingsGetJob...
dhcpv4_manage
Dhcpv4 management - 7 available methods including: leasesDelLease, leasesSearchLease, serviceReconfigure, serviceRestart, serviceStart...
dhcpv6_manage
Dhcpv6 management - 8 available methods including: leasesDelLease, leasesSearchLease, leasesSearchPrefix, serviceReconfigure, serviceRestart...
dhcrelay_manage
Dhcrelay management - 12 available methods including: serviceReconfigure, settingsAddDest, settingsAddRelay, settingsDelDest, settingsDelRelay...
diagnostics_manage
Diagnostics management - 90 available methods including: activityGetActivity, cpuUsageGetCPUType, cpuUsageStream, dnsReverseLookup, dnsDiagnosticsGet...
dnsmasq_manage
Dnsmasq management - 35 available methods including: leasesSearch, serviceReconfigure, serviceRestart, serviceStart, serviceStatus...
firewall_manage
Firewall management - 67 available methods including: aliasAddItem, aliasDelItem, aliasGet, aliasGetAliasUUID, aliasGetGeoIP...
firmware_manage
Firmware management - 26 available methods including: firmwareAudit, firmwareChangelog, firmwareCheck, firmwareConnection, firmwareGet...
ids_manage
Ids management - 40 available methods including: serviceDropAlertLog, serviceGetAlertInfo, serviceGetAlertLogs, serviceQueryAlerts, serviceReconfigure...
interfaces_manage
Network interfaces management - 63 available methods including: gifSettingsAddItem, gifSettingsDelItem, gifSettingsGet, gifSettingsGetIfOptions, gifSettingsGetItem...
ipsec_manage
Ipsec management - 80 available methods including: connectionsAddChild, connectionsAddConnection, connectionsAddLocal, connectionsAddRemote, connectionsConnectionExists...
kea_manage
Kea management - 24 available methods including: ctrlAgentGet, ctrlAgentSet, dhcpv4AddPeer, dhcpv4AddReservation, dhcpv4AddSubnet...
monit_manage
Monit management - 25 available methods including: serviceCheck, serviceReconfigure, serviceRestart, serviceStart, serviceStatus...
openvpn_manage
Openvpn management - 28 available methods including: clientOverwritesAdd, clientOverwritesDel, clientOverwritesGet, clientOverwritesSet, clientOverwritesToggle...
routes_manage
Routes management - 9 available methods including: gatewayStatus, routesAddroute, routesDelroute, routesGet, routesGetroute...
routing_manage
Routing management - 9 available methods including: settingsAddGateway, settingsDelGateway, settingsGet, settingsGetGateway, settingsReconfigure...
syslog_manage
Syslog management - 14 available methods including: serviceReconfigure, serviceReset, serviceRestart, serviceStart, serviceStats...
trafficshaper_manage
Trafficshaper management - 20 available methods including: serviceFlushreload, serviceReconfigure, serviceStatistics, settingsAddPipe, settingsAddQueue...
trust_manage
Trust management - 25 available methods including: caCaInfo, caCaList, caDel, caGenerateFile, caGet...
unbound_manage
Unbound management - 42 available methods including: diagnosticsDumpcache, diagnosticsDumpinfra, diagnosticsListinsecure, diagnosticsListlocaldata, diagnosticsListlocalzones...
wireguard_manage
Wireguard management - 28 available methods including: clientAddClient, clientAddClientBuilder, clientDelClient, clientGet, clientGetClient...
BEFORE YOU INSTALL
What to know first
Tools you get
24 tools when we connected; the project documents 88. The 64 plugin module tools, such as plugin_nginx_manage and plugin_haproxy_manage, load only with --plugins or INCLUDE_PLUGINS set to true, for 88 in total. Each tool is a module that takes a method parameter.
Requires
- npx on PATH
- Node.js 18 or higher
- OPNSENSE_API_KEY in your environment
- OPNSENSE_API_SECRET in your environment
Where it runs
Both documented clients run the server on your machine.
INSTALLATION
Connect your client
Server setup
TERMINAL
npm install -g @richard-stovall/opnsense-mcp-serverMCP Clients
Claude Desktop, Cursor
JSON
{
"mcpServers": {
"opnsense": {
"command": "npx",
"args": [
"-y",
"@richard-stovall/opnsense-mcp-server"
],
"env": {
"OPNSENSE_URL": "https://192.168.1.1",
"OPNSENSE_API_KEY": "<YOUR_OPNSENSE_API_KEY>",
"OPNSENSE_API_SECRET": "<YOUR_OPNSENSE_API_SECRET>",
"OPNSENSE_VERIFY_SSL": "false"
}
}
}
}
