OPNSense MCP Server
by
Manage OPNsense firewalls through conversational AI, providing network configuration, device discovery, DNS filtering, HAProxy setup, and backup/restore via simple commands.
OPNSense MCP Server Overview
What is OPNSense MCP Server about?
Enables control of OPNsense firewalls using natural‑language instructions. The server translates Claude Desktop or Claude Code queries into OPNsense API calls, handling VLANs, rules, device lookup, DNS filtering, HAProxy, and IaC deployments.
How to use OPNSense MCP Server?
- Installation – Run the server with NPX (no global install required):
or install globally withnpx opnsense-mcp-servernpm i -g opnsense-mcp-server. - Add to Claude configuration – Insert an MCP entry in
claude_desktop_config.json(macOS, Windows, Linux) or.claude/config.jsonfor Claude Code. Use the NPX command and provide the required environment variables (OPNSENSE_HOST,OPNSENSE_API_KEY,OPNSENSE_API_SECRET, optionalOPNSENSE_VERIFY_SSL). - Start interacting – Launch Claude Desktop/Code and issue natural‑language commands such as “Create a guest network on VLAN 50” or “Block social media sites”. The server processes the request and applies the changes via the OPNsense API.
Key Features
- Network Management – Create/manage VLANs, interfaces, and firewall rules.
- Device Discovery – Query ARP tables, DHCP leases, and perform network scans.
- DNS Filtering – Block domains or whole categories.
- HAProxy Configuration – Set up load balancing and reverse proxy rules.
- Infrastructure as Code – Declarative deployment of complete network setups.
- Backup & Restore – Export and import OPNsense configuration snapshots.
- Dual Transport – Works directly with Claude Desktop or as a standalone HTTP server.
- Caching & Logging – Optional response caching and adjustable log levels.
Use Cases
- Quickly provision a secure guest Wi‑Fi network.
- Enforce content filters (e.g., block gambling or adult sites) without manual rule editing.
- Discover all devices on the network for inventory or security audits.
- Deploy HAProxy load‑balancing for web services using a single chat command.
- Automate backup of firewall configuration before major changes.
FAQ
Q: Do I need to install anything on the OPNsense appliance? A: Only enable the built‑in API (System → Settings → Administration → Enable API) and create an API user with appropriate privileges.
Q: Can I store API credentials securely?
A: Yes. Use the system keychain syntax {{keychain:opnsense-api-key}} in the MCP configuration to pull secrets from macOS Keychain, Windows Credential Manager, or Linux Secret Service.
Q: What Node.js version is required? A: Node 18 or newer.
Q: How do I run the server in HTTP mode for automation?
A: Execute npm run start:sse (default port 3000) and point your automation tools to http://localhost:3000.
Q: What if Claude cannot connect to the server?
A: Verify the NPX command path, ensure all environment variables are set correctly (host must include https://), and test the server manually via npx opnsense-mcp-server.
OPNSense MCP Server's README
OPNSense MCP Server
A Model Context Protocol (MCP) server for managing OPNsense firewalls through Claude Desktop or Claude Code.
What is this?
OPNSense MCP Server enables you to control your OPNsense firewall using conversational AI. Instead of navigating complex firewall interfaces, simply tell Claude what you want to do.
Example interactions:
- "Create a guest network on VLAN 50"
- "Block social media sites on the network"
- "Find all devices connected in the last hour"
- "Set up port forwarding for my Minecraft server"
✨ Key Features
- Network Management - VLANs, interfaces, firewall rules
- Device Discovery - ARP tables, DHCP leases, network scanning
- DNS Filtering - Block unwanted domains and categories
- HAProxy - Load balancing and reverse proxy configuration
- Infrastructure as Code - Declarative network deployments
- Backup & Restore - Configuration management
- Dual Transport - Works with Claude Desktop and as HTTP server
🚀 Quick Start
Prerequisites
- Node.js 18+
- OPNsense firewall with API access enabled
- Claude Desktop or Claude Code
Installation
Via npm (Recommended)
# Use directly with npx - no installation needed
npx opnsense-mcp-server
# Or install globally
npm install -g opnsense-mcp-server
Via GitHub (Latest Development)
# Use latest from GitHub
npx github:vespo92/OPNSenseMCP
For Development
git clone https://github.com/vespo92/OPNSenseMCP
cd OPNSenseMCP
npm install
npm run build
📋 Configuration
Claude Desktop
Add to your Claude Desktop configuration file:
- MacOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/claude/claude_desktop_config.json
{
"mcpServers": {
"opnsense": {
"command": "npx",
"args": ["--yes", "opnsense-mcp-server@latest"],
"env": {
"OPNSENSE_HOST": "https://192.168.1.1",
"OPNSENSE_API_KEY": "your-api-key",
"OPNSENSE_API_SECRET": "your-api-secret",
"OPNSENSE_VERIFY_SSL": "true"
}
}
}
}
Claude Code
Add to .claude/config.json in your project root:
Option 1: Using NPX (Recommended)
{
"mcpServers": {
"opnsense": {
"command": "npx",
"args": ["--yes", "opnsense-mcp-server@latest"],
"env": {
"OPNSENSE_HOST": "https://192.168.1.1",
"OPNSENSE_API_KEY": "your-api-key",
"OPNSENSE_API_SECRET": "your-api-secret",
"OPNSENSE_VERIFY_SSL": "true"
}
}
}
}
Option 2: Local Installation
{
"mcpServers": {
"opnsense": {
"command": "node",
"args": ["node_modules/opnsense-mcp-server/dist/index.js"],
"env": {
"OPNSENSE_HOST": "https://192.168.1.1",
"OPNSENSE_API_KEY": "your-api-key",
"OPNSENSE_API_SECRET": "your-api-secret",
"OPNSENSE_VERIFY_SSL": "true"
}
}
}
}
Using System Keychain (Recommended for Security)
Instead of hardcoding credentials:
{
"mcpServers": {
"opnsense": {
"command": "npx",
"args": ["opnsense-mcp-server"],
"env": {
"OPNSENSE_HOST": "https://192.168.1.1",
"OPNSENSE_API_KEY": "{{keychain:opnsense-api-key}}",
"OPNSENSE_API_SECRET": "{{keychain:opnsense-api-secret}}",
"OPNSENSE_VERIFY_SSL": "true"
}
}
}
}
Then store credentials in your system keychain:
- MacOS: Use Keychain Access app
- Windows: Use Credential Manager
- Linux: Use Secret Service (gnome-keyring or KWallet)
Environment Variables
| Variable | Description | Required | Default |
|---|---|---|---|
OPNSENSE_HOST |
OPNsense URL (include https://) | Yes | - |
OPNSENSE_API_KEY |
API key from OPNsense | Yes | - |
OPNSENSE_API_SECRET |
API secret from OPNsense | Yes | - |
OPNSENSE_VERIFY_SSL |
Verify SSL certificates | No | true |
LOG_LEVEL |
Logging level | No | info |
CACHE_ENABLED |
Enable response caching | No | true |
CACHE_TTL |
Cache time-to-live in seconds | No | 300 |
{
"mcpServers": {
"opnsense": {
"command": "npx",
"args": ["opnsense-mcp-server"],
"env": {
"OPNSENSE_HOST": "https://192.168.1.1",
"OPNSENSE_API_KEY": "{{keychain:opnsense-api-key}}",
"OPNSENSE_API_SECRET": "{{keychain:opnsense-api-secret}}",
// Optional: Redis cache configuration
// "REDIS_HOST": "localhost",
// "REDIS_PORT": "6379",
// "REDIS_PASSWORD": "{{keychain:redis-password}}",
// "REDIS_DB": "0",
// Optional: PostgreSQL for state persistence
// "POSTGRES_HOST": "localhost",
// "POSTGRES_PORT": "5432",
// "POSTGRES_DB": "opnsense_mcp",
// "POSTGRES_USER": "mcp_user",
// "POSTGRES_PASSWORD": "{{keychain:postgres-password}}",
// Optional: State encryption
// "STATE_ENCRYPTION_KEY": "{{keychain:state-encryption-key}}",
// Optional: Performance tuning
// "CACHE_COMPRESSION_ENABLED": "true",
// "CACHE_COMPRESSION_THRESHOLD": "1024",
// "MAX_CONCURRENT_REQUESTS": "10"
}
}
}
}
🔑 OPNsense API Setup
-
Enable API in OPNsense:
- Navigate to: System → Settings → Administration
- Check: "Enable API"
- Save
-
Create API credentials:
- Navigate to: System → Access → Users
- Edit user or create new
- Under "API Keys", click "+" to generate key/secret
- Save credentials securely
-
Required privileges:
- System: API access
- Firewall: Rules: Edit
- Interfaces: VLANs: Edit
- Services: All
Then restart Claude Desktop/Code and start chatting!
📚 Documentation
- Getting Started Guide - Installation and setup
- Feature Guides - Learn specific features
- IaC Documentation - Infrastructure as Code
- API Reference - Complete tool reference
- Troubleshooting - Common issues and solutions
💡 Example Use Cases
Create a Secure Guest Network
"Create a guest network on VLAN 20 with internet access only"
Find Devices
"Show me all devices from Apple on my network"
Block Unwanted Content
"Block gambling and adult content sites"
Set Up Services
"Configure HAProxy to load balance my web servers"
More examples in the examples/ directory.
🛠️ Advanced Usage
Server Mode (for agents and automation)
npm run start:sse # HTTP server on port 3000
Infrastructure as Code
Deploy entire network configurations declaratively. See IaC documentation.
Custom Patterns
Build reusable network templates. See pattern examples.
🤝 Contributing
We welcome contributions! Please see our Contributing Guide for details.
Development Setup
npm install
npm run dev # Development mode with hot reload
🔧 Troubleshooting
Claude Code/Desktop Not Connecting
If the MCP server fails to connect:
-
Check the command path:
- For NPX: Use
["npx", "--yes", "opnsense-mcp-server@latest"]to ensure latest version - For local: Ensure path is correct:
node_modules/opnsense-mcp-server/dist/index.js
- For NPX: Use
-
Verify environment variables:
- Host must include protocol:
https://192.168.1.1not just192.168.1.1 - API credentials must match exactly (no extra spaces)
- Host must include protocol:
-
Test standalone first:
npx opnsense-mcp-server # Or if installed locally: node node_modules/opnsense-mcp-server/dist/index.js -
Check Claude logs:
- MacOS:
~/Library/Logs/Claude/ - Windows:
%APPDATA%\Claude\logs\ - Linux:
~/.config/claude/logs/
- MacOS:
Common Issues
- "command not found": Install globally with
npm i -g opnsense-mcp-serveror use npx - "EACCES permission denied": The package may need executable permissions
- "Cannot connect to OPNsense": Check firewall rules and API settings
📄 License
MIT License - see LICENSE for details.
🔗 Links
Built with ❤️ for the MCP ecosystem
OPNSense MCP Server Reviews
Login Required
Please log in to share your review and rating for this MCP.
Actions
OPNSense MCP Server's Information
Configuration
{
"mcpServers": {
"opnsense": {
"command": "npx",
"args": [
"-y",
"opnsense-mcp-server@latest"
],
"env": {
"OPNSENSE_HOST": "https://<YOUR_OPNSENSE_IP_OR_HOST>",
"OPNSENSE_API_KEY": "<YOUR_API_KEY>",
"OPNSENSE_API_SECRET": "<YOUR_API_SECRET>",
"OPNSENSE_VERIFY_SSL": "true"
}
}
}
}Configure Clients
Similar MCP Servers like OPNSense MCP Server
Explore related MCPs that share similar capabilities and solve comparable challenges
SafeLine
by chaitin
A self‑hosted web application firewall and reverse proxy that protects web applications from attacks and exploits by filtering, monitoring, and blocking malicious HTTP/S traffic.
Burp MCP Server
by PortSwigger
Enables Burp Suite to communicate with AI clients via the Model Context Protocol, providing an MCP server and bundled stdio proxy.
Cycode CLI
by cycodehq
Boost security in the development lifecycle via SAST, SCA, secrets, and IaC scanning.
Keycloak MCP Server
by ChristophEnglisch
Provides AI‑powered administration of Keycloak users and realms through the Model Context Protocol, enabling automated creation, deletion, and listing of users and realms from MCP clients such as Claude Desktop.
OpenCTI MCP Server
by Spathodea-Network
Provides a Model Context Protocol server that enables querying and retrieving threat intelligence data from OpenCTI through a standardized interface.
Authenticator App MCP Server
Officialby firstorderai
Provides seamless access to two‑factor authentication codes and passwords for AI agents, enabling automated login while maintaining security.
MalwareBazaar MCP
by mytechnotalent
Provides an AI-driven interface to Malware Bazaar, delivering real-time threat intelligence and sample metadata for authorized cybersecurity research workflows.
Attestable MCP Server
by co-browser
Verify that any MCP server is running the intended and untampered code via hardware attestation.
Shodan Mcp
by Hexix23
Provides a powerful interface to the Shodan API, enabling advanced search, host intelligence, vulnerability discovery, and network mapping for security research.