OPNsenseCAUTION
Modular MCP server for OPNsense firewall management - 88 tools providing access to 2000+ methods through AI assistants
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
A modular Model Context Protocol (MCP) server that provides 88 module-based tools giving access to over 2000 OPNsense firewall management methods through a type-safe TypeScript interface.
Features
- Modular Architecture - 88 logical tools (one per module) instead of 2000+ individual tools
- Complete API Coverage - Access to 752 core methods and 1271 plugin methods
- Type-Safe - Full TypeScript support with @richard-stovall/opnsense-typescript-client v0.5.3
- Plugin Support - Optional support for 64 plugin modules
- Smart Organization - Related operations grouped by module for easier discovery
The MCP server acts as a bridge between AI assistants (like Claude Desktop) and your OPNsense firewall, providing secure API access through a modular tool interface.
Usage in Claude Desktop
Usage in Claude Code
Installation
As an MCP Server
This package is designed to be used as an MCP (Model Context Protocol) server with AI assistants like Claude Desktop, Cursor, or other MCP-compatible clients.
Prerequisites
- Node.js 18 or higher
- An OPNsense firewall with API access enabled
- API key and secret from your OPNsense installation
Install from npm
npm install -g @richard-stovall/opnsense-mcp-server
Usage as an MCP Server
Claude Desktop Configuration
Add the following to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"opnsense": {
"command": "npx",
"args": ["-y", "0d0f43ebd2f7OBSERVED · 2026-10-08Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add opnsense-mcp-server --env OPNSENSE_API_KEY=${OPNSENSE_API_KEY} --env OPNSENSE_API_SECRET=${OPNSENSE_API_SECRET} -- npx -y @richard-stovall/[email protected]{
"mcpServers": {
"opnsense-mcp-server": {
"command": "npx",
"args": [
"-y",
"@richard-stovall/[email protected]"
],
"env": {
"OPNSENSE_API_KEY": "${OPNSENSE_API_KEY}",
"OPNSENSE_API_SECRET": "${OPNSENSE_API_SECRET}"
}
}
}
}Exposed tools (4)
4 read · 0 write · 0 destructive.
| Tool | Risk | Description |
|---|---|---|
auth_manage | read | Authentication management - ${authMethods.length} available methods including: ${authMethods.slice(0, 5).join( |
core_manage | read | Core system management - ${coreMethods.length} available methods including: ${coreMethods.slice(0, 5).join( |
firewall_manage | read | Firewall management - ${firewallMethods.length} available methods including: ${firewallMethods.slice(0, 5).join( |
interfaces_manage | read | Network interfaces management - ${interfacesMethods.length} available methods including: ${interfacesMethods.slice(0, 5).join( |
Trust audit
CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | WARN |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | PASS |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- none-observed
- Network
- declared (3 observation(s))
- Shell
- none-observed
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (8)
-u, --url <url> OPNsense API URL (e.g., https://192.168.1.1)
opnsense-mcp-server --url https://192.168.1.1 --api-key mykey --api-secret mysecret
opnsense-mcp-server --url https://192.168.1.1 --api-key mykey --api-secret mysecret --plugins
.gitlab-ci.yml
.yarnrc.yml
"OPNSENSE_URL": "https://192.168.1.1",
"OPNSENSE_URL": "https://192.168.1.1",
@modelcontextprotocol/sdk, zod, @types/node, tsx, typescript
Gates applied: no_behavioural_pass.
0d0f43ebd2f7full audit observations/trust-audit/mcp-server/pixelworlds__opnsense-2.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-08 | 0d0f43ebd2f7 | CAUTION | B | 89 | first audit |
Questions
What is the OPNsense MCP server?
Modular MCP server for OPNsense firewall management - 88 tools providing access to 2000+ methods through AI assistants
What tools does OPNsense expose?
4 in total: 4 read-only, 0 that write, and 0 that can delete or overwrite. Every one is listed on this page with its risk.
Is OPNsense safe to connect to an agent?
With care. The audit graded it B (89/100) and found 8 things worth knowing before you trust this server, listed below with the exact line each was found on.
What credentials does OPNsense need?
It reads OPNSENSE_API_KEY and OPNSENSE_API_SECRET from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How does OPNsense run?
It speaks stdio, so it runs as a local process your client starts. It is published on npm as @richard-stovall/opnsense-mcp-server at 0.5.3.
How current is this page?
The grade is for one exact copy of the source (0d0f43ebd2f7), read on 2026-10-08. The repository is watched and re-audited when it changes.