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

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

hybrid server

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

Tools

View all 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.

Related Resources

Reddit Discussion about this server

Related MCP Servers

mcp-server-cloudflareofficial
cloudflare
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
Code Analysis MCP Server
saiprashanths
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
Azure MCP Server
kalivaraprasad-gonapa
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
pfSense MCP Server
gensecaihq
-
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

OPNSense MCP Server