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.
Badge for your README
Markdown
[](/listings/vespo92--opnsensemcp)HTML
<a href="/listings/vespo92--opnsensemcp"><img src="/api/listings/vespo92--opnsensemcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
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)
- # OPNsense MCP Server
- [](https://www.npmjs.com/package/opnsense-mcp-server)
- [](https://opensource.org/licenses/MIT)
- 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.
- ## Features
- ### 🔥 Firewall Management
- - Complete CRUD operations for firewall rules
- - Proper handling of API-created "automation rules"
- - Inter-VLAN routing configuration
- - Batch rule creation and management
- - Enhanced persistence with multiple fallback methods
- ### 🌐 NAT Configuration (SSH-based)
- - Outbound NAT rule management
- - NAT mode control (automatic/hybrid/manual/disabled)
- - No-NAT exception rules for inter-VLAN traffic
- - Automated DMZ NAT issue resolution
- - Direct XML configuration manipulation
- ### 🔍 Network Diagnostics
- - Comprehensive routing analysis
- - ARP table inspection with vendor identification
- - Interface configuration management
- - Network connectivity troubleshooting
- - Auto-fix capabilities for common issues
- ### 🖥️ SSH/CLI Execution
- - Direct command execution on OPNsense
- - Configuration file manipulation
- - System-level operations not available via API
- - Service management and restarts
- ### 📊 Additional Capabilities
- - VLAN management
- - DHCP lease viewing and management
- - DNS blocklist configuration
- - HAProxy load balancer support
- - Configuration backup and restore
- - Infrastructure as Code support
- ## Installation
- ### 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:
- ```bash
- npm install -g opnsense-mcp-server
- ```
- 2. Create a `.env` file with your credentials:
- ```bash
- # 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:
- ```bash
- 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.
- ```bash
- # 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):
- ```bash
- curl -fsSL https://bun.sh/install | bash
- ```
- 2. Clone and install:
- ```bash
- 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:
- ```bash
- # Development with hot reload
- bun run dev:bun
- # Production
- bun run start:bun
- ```
- ### Using Bun with Claude Desktop
- ```json
- {
- "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"
- }
- }
- }
- }
- ```
- ## Usage with Claude Desktop (npm)
- Add to your Claude Desktop configuration (`claude_desktop_config.json`):
- ```json
- {
- "mcpServers": {
- "opnsense": {
- "command": "npx",
- "args": ["opnsense-mcp-server"],
- "env": {
- "OPNSENSE_HOST": "https://your-opnsense:port",
- "OPNSENSE_API_KEY": "your-key",
- "OPNSENSE_API_SECRET": "your-secret",
- "OPNSENSE_VERIFY_SSL": "false"
- }
- }
- }
- }
- ```
- ## Common Use Cases
- ### Fix DMZ NAT Issues
- ```javascript
- // Automatically fix DMZ to LAN routing
- await mcp.call('nat_fix_dmz', {
- dmzNetwork: '10.0.6.0/24',
- lanNetwork: '10.0.0.0/24'
- });
- ```
- ### Create Firewall Rules
- ```javascript
- // Allow NFS from DMZ to NAS
- await mcp.call('firewall_create_rule', {
- action: 'pass',
- interface: 'opt8',
- source: '10.0.6.0/24',
- destination: '10.0.0.14/32',
- protocol: 'tcp',
- destination_port: '2049',
- description: 'Allow NFS from DMZ'
- });
- ```
- ### Diagnose Routing Issues
- ```javascript
- // Run comprehensive routing diagnostics
- await mcp.call('routing_diagnostics', {
- sourceNetwork: '10.0.6.0/24',
- destNetwork: '10.0.0.0/24'
- });
- ```
- ### Execute CLI Commands
- ```javascript
- // Run any OPNsense CLI command
- await mcp.call('system_execute_command', {
- command: 'pfctl -s state | grep 10.0.6'
- });
- ```
- ## MCP Tools Reference
- The server provides 50+ MCP tools organized by category:
- ### Firewall Tools
- - `firewall_list_rules` - List all firewall rules
- - `firewall_create_rule` - Create a new rule
- - `firewall_update_rule` - Update existing rule
- - `firewall_delete_rule` - Delete a rule
- - `firewall_apply_changes` - Apply pending changes
- ### NAT Tools
- - `nat_list_outbound` - List outbound NAT rules
- - `nat_set_mode` - Set NAT mode
- - `nat_create_outbound_rule` - Create NAT rule
- - `nat_fix_dmz` - Fix DMZ NAT issues
- - `nat_analyze_config` - Analyze NAT configuration
- ### Network Tools
- - `arp_list` - List ARP table entries
- - `routing_diagnostics` - Diagnose routing issues
- - `routing_fix_all` - Auto-fix routing problems
- - `interface_list` - List network interfaces
- - `vlan_create` - Create VLAN
- ### System Tools
- - `system_execute_command` - Execute CLI command
- - `backup_create` - Create configuration backup
- - `service_restart` - Restart a service
- For a complete list, see [docs/api/mcp-tools.md](docs/api/mcp-tools.md).
- ## Documentation
- - [Quick Start Guide](docs/guides/quick-start.md)
- - [Configuration Guide](docs/guides/configuration.md)
- - [NAT Management](docs/features/nat.md)
- - [SSH/CLI Execution](docs/features/ssh.md)
- - [Firewall Rules](docs/features/firewall.md)
- - [Safety Modes (Dry-Run & Read-Only)](docs/features/safety-modes.md)
- - [Troubleshooting](docs/guides/troubleshooting.md)
- ## Testing
- The repository includes comprehensive testing utilities:
- ```bash
- # Test NAT functionality
- npx tsx scripts/test/test-nat-ssh.ts
- # Test firewall rules
- npx tsx scripts/test/test-rules.ts
- # Test routing diagnostics
- npx tsx scripts/test/test-routing.ts
- # Run all tests
- npm test
- ```
- ## Development
- ### Building from Source
- This repo uses [Bun](https://bun.sh) as its development toolchain (install,
- build, tests). The published package is still plain Node — it is consumed as
- `node dist/index.js` — so Bun is only needed to work *on* the project, not to
- run it.
- ```bash
- git clone https://github.com/vespo92/OPNSenseMCP.git
- cd OPNSenseMCP
- bun install
- bun run build
- bun run test
- ```
- The lockfile is `bun.lock`; there is no `package-lock.json`. CI runs
- `bun install --frozen-lockfile`, so commit `bun.lock` alongside any
- `package.json` change.
- ### Project Structure
- ```
- OPNSenseMCP/
- ├── src/ # Source code
- │ ├── api/ # API client
- │ ├── resources/ # Resource implementations
- │ └── index.ts # MCP server entry
- ├── docs/ # Documentation
- ├── scripts/ # Utility scripts
- │ ├── test/ # Test scripts
- │ ├── debug/ # Debug utilities
- │ └── fixes/ # Fix scripts
- └── dist/ # Build output
- ```
- ## Troubleshooting
- ### API Authentication Failed
- - Verify API key and secret are correct
- - Ensure API access is enabled in OPNsense
- - Check firewall rules allow API access
- ### SSH Connection Failed
- - Verify SSH credentials in `.env`
- - Ensure SSH is enabled on OPNsense
- - Check user has appropriate privileges
- ### NAT Features Not Working
- - NAT management requires SSH access
- - Add SSH credentials to environment variables
- - Test with: `npx tsx scripts/test/test-nat-ssh.ts`
- ## Contributing
- Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
- ## License
- This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
- ## Support
- - **Issues**: [GitHub Issues](https://github.com/vespo92/OPNSenseMCP/issues)
- - **Discussions**: [GitHub Discussions](https://github.com/vespo92/OPNSenseMCP/discussions)
- - **Documentation**: [Full Documentation](docs/)
- ## Acknowledgments
- - Built for use with [Anthropic's Claude](https://claude.ai)
- - Implements the [Model Context Protocol](https://modelcontextprotocol.io)
- - Designed for [OPNsense](https://opnsense.org) firewall
- ---
- **Version**: 0.8.2 | **Status**: Production Ready | **Last Updated**: August 2025
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.