OPNSense MCP

What is OPNSenseMCP?

OPNSenseMCP is a Model Context Protocol (MCP) server that facilitates the management of OPNsense firewalls using Infrastructure as Code (IaC) principles. It acts as a proxy, allowing users to define and deploy their network infrastructure declaratively, similar to how software is developed and deployed.

How to use OPNSenseMCP?

To use OPNSenseMCP, you first need to clone the repository, install dependencies using npm install, and then build the project with npm run build. Configuration can be done via environment variables in a .env file (e.g., OPNSENSE_HOST, OPNSENSE_API_KEY, OPNSENSE_API_SECRET) or through manual configuration within your code. The server supports two transport modes: STDIO for direct integration with Claude Desktop and SSE for HTTP-based integration with agents and containers. You can start the server using npm start for STDIO mode or npm run start:sse for SSE mode.

Key Features of OPNSenseMCP

• Complete OPNsense API Integration: Manage VLANs, firewall rules, services, and more.
• ARP Table Management: View and search ARP entries, and find devices by IP/MAC/hostname.
• Infrastructure as Code (IaC): Deploy and manage network infrastructure declaratively.
• State Management: Track resource state with rollback capabilities.
• Caching Support: Integration with Redis and PostgreSQL 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 and SSE for agents/containers.

Use Cases of OPNSenseMCP

OPNSenseMCP can be used for various network management tasks, including:

• Declarative Network Deployment: Define your network setup (VLANs, firewall rules) in code and deploy it consistently.
• Automated Network Configuration: Automate the creation and modification of firewall rules, VLANs, and other OPNsense settings.
• Guest Network Setup: Easily deploy isolated guest networks with specific firewall rules.
• Device Tracking: Quickly find devices on your network using ARP table management.
• Content Filtering: Implement DNS blocking to restrict access to certain websites.
• Integration with AI Assistants: Use with Claude Desktop to manage your firewall through natural language commands, such as "Create a new VLAN for my smart home devices" or "Block pornhub.com on my network."

FAQ from OPNSenseMCP

Q: What are common issues during connection? A: Connection refused errors often indicate that the OPNsense API is not enabled, firewall rules are blocking access, or SSL settings are incorrect. Authentication failures usually stem from incorrect API key/secret (ensure they are base64 encoded) or insufficient user permissions.

Q: Why is VLAN creation failing? A: Ensure the physical interface exists and is not in use, the VLAN tag is within the valid range (1-4094), and the interface supports VLAN tagging.

Q: How to troubleshoot build errors? A: Try running npm ci for a clean dependency installation. Verify that Node.js 18+ is installed and that your TypeScript version matches the project requirements.

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

# 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

• Getting Started Guide
• API Reference
• IaC Architecture
• Troubleshooting

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