Skip to content
Back to search

OPNSenseMCP

MCP Server for OPNSense to act as IaC proxy

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vespo92--opnsensemcp/badge.svg)](/listings/vespo92--opnsensemcp)

HTML

<a href="/listings/vespo92--opnsensemcp"><img src="/api/listings/vespo92--opnsensemcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Prerequisites

- Node.js 18+ to run the server (Bun 1.1.39+ to develop on it) - OPNsense firewall (v24.7+ recommended) - API credentials for OPNsense - SSH access (optional, for advanced features)

Quick Start with npm

1. Install the package:

npm install -g opnsense-mcp-server

2. Create a `.env` file with your credentials:

# Required
OPNSENSE_HOST=https://your-opnsense-host:port
OPNSENSE_API_KEY=your-api-key
OPNSENSE_API_SECRET=your-api-secret
OPNSENSE_VERIFY_SSL=false

# Optional - for SSH features
OPNSENSE_SSH_HOST=your-opnsense-host
OPNSENSE_SSH_USERNAME=root
OPNSENSE_SSH_PASSWORD=your-password
# Or use SSH key
# OPNSENSE_SSH_KEY_PATH=~/.ssh/id_rsa

# Recommended for a new/production router — see "Safety Modes" below
# OPNSENSE_READ_ONLY=true

3. Start the MCP server:

opnsense-mcp-server

⚠️ Safety Modes (read this before pointing at a production router)

By default this server can make live, immediate changes to your firewall — add/delete rules, change NAT, restart services, run whitelisted shell commands over SSH. Two environment variables (operator-only — a tool call can never set or override them) add a safety net:

| Variable | Effect | |----------|--------| | `OPNSENSE_READ_ONLY=true` | Every mutating API call and every non-read-only SSH command is rejected before it's sent. Write-capable tools are also hidden from the tool list, so the model never sees them as an option. | | `OPNSENSE_DRY_RUN=true` | Mutating calls are simulated instead of sent — you get a log line and a synthetic success response describing what *would* have happened, with no request reaching the router. |

Both are enforced at the two lowest-level chokepoints this server uses to reach the router — the API client and the SSH executor — so they apply uniformly across all 140+ tools, not on a per-tool basis. If both are set, `OPNSENSE_READ_ONLY` wins.

# First time pointing this at a real router? Start here:
OPNSENSE_READ_ONLY=true

# Once you trust it, watch what it would do before going live:
OPNSENSE_DRY_RUN=true

# Remove both once you're confident.

See [CONFIGURATION.md](CONFIGURATION.md#safety-modes) for the config reference, or [docs/features/safety-modes.md](docs/features/safety-modes.md) for how it works under the hood.

Quick Start with Bun (Faster)

[Bun](https://bun.sh) provides significantly faster startup times and better performance.

1. Install Bun (if not already installed):

curl -fsSL https://bun.sh/install | bash

2. Clone and install:

git clone https://github.com/vespo92/OPNSenseMCP.git
cd OPNSenseMCP
bun install

3. Create your `.env` file (same as npm version above)

4. Run with Bun:

# Development with hot reload
bun run dev:bun

# Production
bun run start:bun

Using Bun with Claude Desktop

{
  "mcpServers": {
    "opnsense": {
      "command": "bun",
      "args": ["run", "/path/to/OPNSenseMCP/src/index.ts"],
      "env": {
        "OPNSENSE_HOST": "https://your-opnsense:port",
        "OPNSENSE_API_KEY": "your-key",
        "OPNSENSE_API_SECRET": "your-secret",
        "OPNSENSE_VERIFY_SSL": "false"
      }
    }
  }
}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 359 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # OPNsense MCP Server
  2. [![npm version](https://badge.fury.io/js/opnsense-mcp-server.svg)](https://www.npmjs.com/package/opnsense-mcp-server)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  4. A Model Context Protocol (MCP) server for comprehensive OPNsense firewall management. This server enables AI assistants like Claude to directly manage firewall configurations, diagnose network issues, and automate complex networking tasks.
  5. ## Features
  6. ### 🔥 Firewall Management
  7. - Complete CRUD operations for firewall rules
  8. - Proper handling of API-created "automation rules"
  9. - Inter-VLAN routing configuration
  10. - Batch rule creation and management
  11. - Enhanced persistence with multiple fallback methods
  12. ### 🌐 NAT Configuration (SSH-based)
  13. - Outbound NAT rule management
  14. - NAT mode control (automatic/hybrid/manual/disabled)
  15. - No-NAT exception rules for inter-VLAN traffic
  16. - Automated DMZ NAT issue resolution
  17. - Direct XML configuration manipulation
  18. ### 🔍 Network Diagnostics
  19. - Comprehensive routing analysis
  20. - ARP table inspection with vendor identification
  21. - Interface configuration management
  22. - Network connectivity troubleshooting
  23. - Auto-fix capabilities for common issues
  24. ### 🖥️ SSH/CLI Execution
  25. - Direct command execution on OPNsense
  26. - Configuration file manipulation
  27. - System-level operations not available via API
  28. - Service management and restarts
  29. ### 📊 Additional Capabilities
  30. - VLAN management
  31. - DHCP lease viewing and management
  32. - DNS blocklist configuration
  33. - HAProxy load balancer support
  34. - Configuration backup and restore
  35. - Infrastructure as Code support
  36. ## Installation
  37. ### Prerequisites
  38. - Node.js 18+ to run the server (Bun 1.1.39+ to develop on it)
  39. - OPNsense firewall (v24.7+ recommended)
  40. - API credentials for OPNsense
  41. - SSH access (optional, for advanced features)
  42. ### Quick Start with npm
  43. 1. Install the package:
  44. ```bash
  45. npm install -g opnsense-mcp-server
  46. ```
  47. 2. Create a `.env` file with your credentials:
  48. ```bash
  49. # Required
  50. OPNSENSE_HOST=https://your-opnsense-host:port
  51. OPNSENSE_API_KEY=your-api-key
  52. OPNSENSE_API_SECRET=your-api-secret
  53. OPNSENSE_VERIFY_SSL=false
  54. # Optional - for SSH features
  55. OPNSENSE_SSH_HOST=your-opnsense-host
  56. OPNSENSE_SSH_USERNAME=root
  57. OPNSENSE_SSH_PASSWORD=your-password
  58. # Or use SSH key
  59. # OPNSENSE_SSH_KEY_PATH=~/.ssh/id_rsa
  60. # Recommended for a new/production router — see "Safety Modes" below
  61. # OPNSENSE_READ_ONLY=true
  62. ```
  63. 3. Start the MCP server:
  64. ```bash
  65. opnsense-mcp-server
  66. ```
  67. ### ⚠️ Safety Modes (read this before pointing at a production router)
  68. By default this server can make live, immediate changes to your firewall —
  69. add/delete rules, change NAT, restart services, run whitelisted shell
  70. commands over SSH. Two environment variables (operator-only — a tool call
  71. can never set or override them) add a safety net:
  72. | Variable | Effect |
  73. |----------|--------|
  74. | `OPNSENSE_READ_ONLY=true` | Every mutating API call and every non-read-only SSH command is rejected before it's sent. Write-capable tools are also hidden from the tool list, so the model never sees them as an option. |
  75. | `OPNSENSE_DRY_RUN=true` | Mutating calls are simulated instead of sent — you get a log line and a synthetic success response describing what *would* have happened, with no request reaching the router. |
  76. Both are enforced at the two lowest-level chokepoints this server uses to
  77. reach the router — the API client and the SSH executor — so they apply
  78. uniformly across all 140+ tools, not on a per-tool basis. If both are set,
  79. `OPNSENSE_READ_ONLY` wins.
  80. ```bash
  81. # First time pointing this at a real router? Start here:
  82. OPNSENSE_READ_ONLY=true
  83. # Once you trust it, watch what it would do before going live:
  84. OPNSENSE_DRY_RUN=true
  85. # Remove both once you're confident.
  86. ```
  87. See [CONFIGURATION.md](CONFIGURATION.md#safety-modes) for the config
  88. reference, or [docs/features/safety-modes.md](docs/features/safety-modes.md)
  89. for how it works under the hood.
  90. ### Quick Start with Bun (Faster)
  91. [Bun](https://bun.sh) provides significantly faster startup times and better performance.
  92. 1. Install Bun (if not already installed):
  93. ```bash
  94. curl -fsSL https://bun.sh/install | bash
  95. ```
  96. 2. Clone and install:
  97. ```bash
  98. git clone https://github.com/vespo92/OPNSenseMCP.git
  99. cd OPNSenseMCP
  100. bun install
  101. ```
  102. 3. Create your `.env` file (same as npm version above)
  103. 4. Run with Bun:
  104. ```bash
  105. # Development with hot reload
  106. bun run dev:bun
  107. # Production
  108. bun run start:bun
  109. ```
  110. ### Using Bun with Claude Desktop
  111. ```json
  112. {
  113. "mcpServers": {
  114. "opnsense": {
  115. "command": "bun",
  116. "args": ["run", "/path/to/OPNSenseMCP/src/index.ts"],
  117. "env": {
  118. "OPNSENSE_HOST": "https://your-opnsense:port",
  119. "OPNSENSE_API_KEY": "your-key",
  120. "OPNSENSE_API_SECRET": "your-secret",
  121. "OPNSENSE_VERIFY_SSL": "false"
  122. }
  123. }
  124. }
  125. }
  126. ```
  127. ## Usage with Claude Desktop (npm)
  128. Add to your Claude Desktop configuration (`claude_desktop_config.json`):
  129. ```json
  130. {
  131. "mcpServers": {
  132. "opnsense": {
  133. "command": "npx",
  134. "args": ["opnsense-mcp-server"],
  135. "env": {
  136. "OPNSENSE_HOST": "https://your-opnsense:port",
  137. "OPNSENSE_API_KEY": "your-key",
  138. "OPNSENSE_API_SECRET": "your-secret",
  139. "OPNSENSE_VERIFY_SSL": "false"
  140. }
  141. }
  142. }
  143. }
  144. ```
  145. ## Common Use Cases
  146. ### Fix DMZ NAT Issues
  147. ```javascript
  148. // Automatically fix DMZ to LAN routing
  149. await mcp.call('nat_fix_dmz', {
  150. dmzNetwork: '10.0.6.0/24',
  151. lanNetwork: '10.0.0.0/24'
  152. });
  153. ```
  154. ### Create Firewall Rules
  155. ```javascript
  156. // Allow NFS from DMZ to NAS
  157. await mcp.call('firewall_create_rule', {
  158. action: 'pass',
  159. interface: 'opt8',
  160. source: '10.0.6.0/24',
  161. destination: '10.0.0.14/32',
  162. protocol: 'tcp',
  163. destination_port: '2049',
  164. description: 'Allow NFS from DMZ'
  165. });
  166. ```
  167. ### Diagnose Routing Issues
  168. ```javascript
  169. // Run comprehensive routing diagnostics
  170. await mcp.call('routing_diagnostics', {
  171. sourceNetwork: '10.0.6.0/24',
  172. destNetwork: '10.0.0.0/24'
  173. });
  174. ```
  175. ### Execute CLI Commands
  176. ```javascript
  177. // Run any OPNsense CLI command
  178. await mcp.call('system_execute_command', {
  179. command: 'pfctl -s state | grep 10.0.6'
  180. });
  181. ```
  182. ## MCP Tools Reference
  183. The server provides 50+ MCP tools organized by category:
  184. ### Firewall Tools
  185. - `firewall_list_rules` - List all firewall rules
  186. - `firewall_create_rule` - Create a new rule
  187. - `firewall_update_rule` - Update existing rule
  188. - `firewall_delete_rule` - Delete a rule
  189. - `firewall_apply_changes` - Apply pending changes
  190. ### NAT Tools
  191. - `nat_list_outbound` - List outbound NAT rules
  192. - `nat_set_mode` - Set NAT mode
  193. - `nat_create_outbound_rule` - Create NAT rule
  194. - `nat_fix_dmz` - Fix DMZ NAT issues
  195. - `nat_analyze_config` - Analyze NAT configuration
  196. ### Network Tools
  197. - `arp_list` - List ARP table entries
  198. - `routing_diagnostics` - Diagnose routing issues
  199. - `routing_fix_all` - Auto-fix routing problems
  200. - `interface_list` - List network interfaces
  201. - `vlan_create` - Create VLAN
  202. ### System Tools
  203. - `system_execute_command` - Execute CLI command
  204. - `backup_create` - Create configuration backup
  205. - `service_restart` - Restart a service
  206. For a complete list, see [docs/api/mcp-tools.md](docs/api/mcp-tools.md).
  207. ## Documentation
  208. - [Quick Start Guide](docs/guides/quick-start.md)
  209. - [Configuration Guide](docs/guides/configuration.md)
  210. - [NAT Management](docs/features/nat.md)
  211. - [SSH/CLI Execution](docs/features/ssh.md)
  212. - [Firewall Rules](docs/features/firewall.md)
  213. - [Safety Modes (Dry-Run & Read-Only)](docs/features/safety-modes.md)
  214. - [Troubleshooting](docs/guides/troubleshooting.md)
  215. ## Testing
  216. The repository includes comprehensive testing utilities:
  217. ```bash
  218. # Test NAT functionality
  219. npx tsx scripts/test/test-nat-ssh.ts
  220. # Test firewall rules
  221. npx tsx scripts/test/test-rules.ts
  222. # Test routing diagnostics
  223. npx tsx scripts/test/test-routing.ts
  224. # Run all tests
  225. npm test
  226. ```
  227. ## Development
  228. ### Building from Source
  229. This repo uses [Bun](https://bun.sh) as its development toolchain (install,
  230. build, tests). The published package is still plain Node — it is consumed as
  231. `node dist/index.js` — so Bun is only needed to work *on* the project, not to
  232. run it.
  233. ```bash
  234. git clone https://github.com/vespo92/OPNSenseMCP.git
  235. cd OPNSenseMCP
  236. bun install
  237. bun run build
  238. bun run test
  239. ```
  240. The lockfile is `bun.lock`; there is no `package-lock.json`. CI runs
  241. `bun install --frozen-lockfile`, so commit `bun.lock` alongside any
  242. `package.json` change.
  243. ### Project Structure
  244. ```
  245. OPNSenseMCP/
  246. ├── src/ # Source code
  247. │ ├── api/ # API client
  248. │ ├── resources/ # Resource implementations
  249. │ └── index.ts # MCP server entry
  250. ├── docs/ # Documentation
  251. ├── scripts/ # Utility scripts
  252. │ ├── test/ # Test scripts
  253. │ ├── debug/ # Debug utilities
  254. │ └── fixes/ # Fix scripts
  255. └── dist/ # Build output
  256. ```
  257. ## Troubleshooting
  258. ### API Authentication Failed
  259. - Verify API key and secret are correct
  260. - Ensure API access is enabled in OPNsense
  261. - Check firewall rules allow API access
  262. ### SSH Connection Failed
  263. - Verify SSH credentials in `.env`
  264. - Ensure SSH is enabled on OPNsense
  265. - Check user has appropriate privileges
  266. ### NAT Features Not Working
  267. - NAT management requires SSH access
  268. - Add SSH credentials to environment variables
  269. - Test with: `npx tsx scripts/test/test-nat-ssh.ts`
  270. ## Contributing
  271. Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
  272. ## License
  273. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  274. ## Support
  275. - **Issues**: [GitHub Issues](https://github.com/vespo92/OPNSenseMCP/issues)
  276. - **Discussions**: [GitHub Discussions](https://github.com/vespo92/OPNSenseMCP/discussions)
  277. - **Documentation**: [Full Documentation](docs/)
  278. ## Acknowledgments
  279. - Built for use with [Anthropic's Claude](https://claude.ai)
  280. - Implements the [Model Context Protocol](https://modelcontextprotocol.io)
  281. - Designed for [OPNsense](https://opnsense.org) firewall
  282. ---
  283. **Version**: 0.8.2 | **Status**: Production Ready | **Last Updated**: August 2025

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.