The OPNSense MCP Server enables Infrastructure as Code (IaC) management of OPNsense firewalls through comprehensive API integration. With this server, you can:
- Configure OPNsense Connection: Set up host, API key, and secret for firewall communication
- Test Connectivity: Verify API connection and authentication
- Manage VLANs: List, create, update, delete, and retrieve VLAN details
- Control Firewall Rules: List, create, update, delete, enable/disable, and search rules; supports predefined rule presets
- Handle Backups: Create, list, and restore configuration backups
- Network Operations: Retrieve available network interfaces and configure isolated networks
- DNS Management: Manage DNS blocklists
- IaC Integration: Declaratively manage OPNsense infrastructure using JSON or JavaScript
Provides tools for managing OPNSense firewalls, including VLAN creation and management, firewall rule configuration, network interface queries, and DHCP lease management
Implements an audit database for tracking changes made through the OPNSense MCP server
Used as an optional cache layer for improved performance in Phase 3 of the OPNSense MCP server
OPNSense MCP Server
A Model Context Protocol (MCP) server for managing OPNsense firewalls with Infrastructure as Code (IaC) capabilities.
Features
=======
🚀 Features
- Complete OPNsense API Integration - Manage VLANs, firewall rules, services, and more
- ARP Table Management - View and search ARP entries, find devices by IP/MAC/hostname
- Infrastructure as Code - Deploy and manage network infrastructure declaratively
- State Management - Track resource state with rollback capabilities
- Caching Support - Redis and PostgreSQL integration for performance
- DNS Blocking - Built-in DNS blocklist management
- HAProxy Support - Full HAProxy configuration and management
- Backup & Restore - Configuration backup management
- Dual Transport Support - STDIO for Claude Desktop, SSE for agents/containers
📋 Prerequisites
- Node.js 18+
- OPNsense firewall with API access enabled
- (Optional) Redis for caching
- (Optional) PostgreSQL for persistent cache
🛠️ Installation
🚀 Transport Modes
The server supports two transport modes:
STDIO Mode (Default)
For direct integration with Claude Desktop:
SSE Mode
For HTTP-based integration with agents and containers:
SSE Endpoints:
GET /sse
- SSE connection endpointPOST /messages
- Message handlingGET /health
- Health check
See SSE Deployment Guide for container deployment.
⚙️ Configuration
The server supports multiple configuration methods:
Environment Variables (Auto-configuration)
The server automatically attempts to connect using environment variables on startup. Create a .env
file:
Manual Configuration
If environment variables are not set or connection fails, use the configure
tool:
🚦 Quick Start
📚 Documentation
Infrastructure as Code Example
Deploy network infrastructure declaratively:
📖 Usage Examples
Managing VLANs
Firewall Rules
DNS Blocking
Complete Network Setup Example
Using with Claude Desktop
Once configured in Claude Desktop, you can ask Claude to:
- "Create a new VLAN for my smart home devices"
- "Show me all devices on my guest network"
- "Block pornhub.com on my network"
- "Set up a Minecraft server VLAN with proper firewall rules"
- "Find Kyle's laptop on the network"
- "Create a backup of my firewall configuration"
🔧 Troubleshooting
Common Issues
Connection refused errors
- Ensure OPNsense API is enabled (System > Settings > Administration > API)
- Check firewall rules allow API access from your host
- Verify SSL settings match your configuration
Authentication failures
- API key and secret must be base64 encoded in OPNsense
- Ensure no trailing spaces in credentials
- Check user has appropriate permissions
VLAN creation fails
- Verify the physical interface exists and is not in use
- Check VLAN tag is within valid range (1-4094)
- Ensure interface supports VLAN tagging
Build errors
- Run
npm ci
for clean dependency installation - Ensure Node.js 18+ is installed
- Check TypeScript version matches requirements
For more detailed troubleshooting, see our Troubleshooting Guide.
🗺️ Roadmap
- Unified IaC orchestrator
- Web UI for deployment management
- Multi-firewall support
🤝 Contributing
Contributions are welcome! Please read our Contributing Guide for details.
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
- Built for the MCP (Model Context Protocol) ecosystem
- Inspired by Pulumi and SST infrastructure patterns
- Part of a larger vision for home infrastructure automation
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
A server that enables managing OPNSense firewalls through natural language interactions with Claude Desktop, supporting VLAN management, firewall rules configuration, and network interface queries.
- Features
- 🚀 Features
- 📋 Prerequisites
- 🛠️ Installation
- 🚀 Transport Modes
- ⚙️ Configuration
- 🚦 Quick Start
- 📚 Documentation
- 📖 Usage Examples
- 🔧 Troubleshooting
- 🗺️ Roadmap
- 🤝 Contributing
- 📄 License
- 🙏 Acknowledgments
Related Resources
Related MCP Servers
- AsecurityAlicenseAqualityLets you use Claude Desktop, or any MCP Client, to use natural language to accomplish things on your Cloudflare account.Last updated -21,3142,763TypeScriptApache 2.0
- AsecurityFlicenseAqualityThe server facilitates natural language interactions for exploring and understanding codebases, providing insights into data models and system architecture using a cost-effective, simple setup with support for existing Claude Pro subscriptions.Last updated -416Python
- AsecurityAlicenseAqualityEnables natural language interaction with Azure services through Claude Desktop, supporting resource management, subscription handling, and tenant selection with secure authentication.Last updated -31113TypeScriptMIT License
- -securityAlicense-qualityA production-grade server that enables natural language interaction with pfSense firewalls through Claude Desktop and other GenAI applications, supporting multiple access levels and functional categories.Last updated -6PythonMIT License