Skip to main content
Glama

OPNSense MCP Server

OPNSense MCP Server

A Model Context Protocol (MCP) server for managing OPNsense firewalls with Infrastructure as Code (IaC) capabilities.

Features

======= Version License MCP

🚀 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

# Clone the repository git clone https://github.com/vespo92/OPNSenseMCP cd opnsense-mcp # Install dependencies npm install # Build the project npm run build # Copy and configure environment cp .env.example .env # Edit .env with your OPNsense credentials

🚀 Transport Modes

The server supports two transport modes:

STDIO Mode (Default)

For direct integration with Claude Desktop:

npm start # or npm run start:stdio

SSE Mode

For HTTP-based integration with agents and containers:

npm run start:sse # Starts on port 3000 npm run start:sse -- --port 8080 # Custom port

SSE Endpoints:

  • GET /sse - SSE connection endpoint
  • POST /messages - Message handling
  • GET /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:

# Required OPNSENSE_HOST=https://192.168.1.1 # or just 192.168.1.1:55443 OPNSENSE_API_KEY=your_api_key OPNSENSE_API_SECRET=your_api_secret # Optional IAC_ENABLED=true ENABLE_CACHE=false REDIS_HOST=localhost POSTGRES_HOST=localhost

Manual Configuration

If environment variables are not set or connection fails, use the configure tool:

// Configure connection manually await configure({ host: "https://192.168.1.1", apiKey: "your_api_key", apiSecret: "your_api_secret", verifySsl: true });

🚦 Quick Start

# Start the MCP server npm start # Or use with Claude Desktop # Add to claude_desktop_config.json: { "mcpServers": { "opnsense": { "command": "node", "args": ["dist/index.js"], "cwd": "/path/to/opnsense-mcp", "env": { "OPNSENSE_HOST": "https://192.168.1.1:55443", "OPNSENSE_API_KEY": "your_api_key", "OPNSENSE_API_SECRET": "your_api_secret", "OPNSENSE_VERIFY_SSL": "true" } } } }

📚 Documentation

Infrastructure as Code Example

Deploy network infrastructure declaratively:

{ "name": "home-network", "resources": [{ "type": "opnsense:network:vlan", "id": "guest-vlan", "name": "Guest Network", "properties": { "interface": "igc3", "tag": 10, "description": "Isolated guest network" } }] }

📖 Usage Examples

Managing VLANs

// Create a new VLAN for IoT devices const vlan = { type: "opnsense:network:vlan", properties: { interface: "igc3", tag: 20, description: "IoT Network - Isolated" } };

Firewall Rules

// Block all traffic from guest network to main LAN const rule = { type: "opnsense:firewall:rule", properties: { action: "block", interface: "guest_vlan", source: "guest_vlan_subnet", destination: "lan_subnet", description: "Block guest to LAN" } };

DNS Blocking

// Block social media sites const blocklist = { type: "opnsense:dns:blocklist", properties: { domains: ["facebook.com", "twitter.com", "tiktok.com"], description: "Social media block", enabled: true } };

Complete Network Setup Example

// Deploy a complete guest network with isolation const guestNetwork = { name: "guest-network-setup", resources: [ { type: "opnsense:network:vlan", id: "guest-vlan", properties: { interface: "igc3", tag: 10, description: "Guest WiFi Network" } }, { type: "opnsense:firewall:rule", id: "guest-internet", properties: { action: "pass", interface: "guest_vlan", source: "guest_vlan_subnet", destination: "any", description: "Allow guest internet" } }, { type: "opnsense:firewall:rule", id: "block-guest-lan", properties: { action: "block", interface: "guest_vlan", source: "guest_vlan_subnet", destination: "lan_subnet", description: "Isolate guest from LAN" } } ] };

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
Install Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

A server that enables managing OPNSense firewalls through natural language interactions with Claude Desktop, supporting VLAN management, firewall rules configuration, and network interface queries.

  1. Features
    1. 🚀 Features
      1. 📋 Prerequisites
        1. 🛠️ Installation
          1. 🚀 Transport Modes
            1. STDIO Mode (Default)
            2. SSE Mode
          2. ⚙️ Configuration
            1. Environment Variables (Auto-configuration)
            2. Manual Configuration
          3. 🚦 Quick Start
            1. 📚 Documentation
              1. Infrastructure as Code Example
            2. 📖 Usage Examples
              1. Managing VLANs
              2. Firewall Rules
              3. DNS Blocking
              4. Complete Network Setup Example
              5. Using with Claude Desktop
            3. 🔧 Troubleshooting
              1. Common Issues
            4. 🗺️ Roadmap
              1. 🤝 Contributing
                1. 📄 License
                  1. 🙏 Acknowledgments

                    Related MCP Servers

                    • A
                      security
                      A
                      license
                      A
                      quality
                      Lets you use Claude Desktop, or any MCP Client, to use natural language to accomplish things on your Cloudflare account.
                      Last updated -
                      2
                      1,314
                      2,763
                      TypeScript
                      Apache 2.0
                      • Apple
                    • A
                      security
                      F
                      license
                      A
                      quality
                      The 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 -
                      4
                      16
                      Python
                      • Apple
                    • A
                      security
                      A
                      license
                      A
                      quality
                      Enables natural language interaction with Azure services through Claude Desktop, supporting resource management, subscription handling, and tenant selection with secure authentication.
                      Last updated -
                      3
                      11
                      13
                      TypeScript
                      MIT License
                    • -
                      security
                      A
                      license
                      -
                      quality
                      A 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 -
                      6
                      Python
                      MIT License

                    View all related MCP servers

                    MCP directory API

                    We provide all the information about MCP servers via our MCP API.

                    curl -X GET 'https://glama.ai/api/mcp/v1/servers/vespo92/OPNSenseMCP'

                    If you have feedback or need assistance with the MCP directory API, please join our Discord server