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

{
  "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

1. Enable API in OPNsense:

   • Navigate to: System → Settings → Administration
   • Check: "Enable API"
   • Save

2. Create API credentials:

   • Navigate to: System → Access → Users
   • Edit user or create new
   • Under "API Keys", click "+" to generate key/secret
   • Save credentials securely

3. 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:

1. 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

2. Verify environment variables:

   • Host must include protocol: https://192.168.1.1 not just 192.168.1.1
   • API credentials must match exactly (no extra spaces)

3. Test standalone first:

   npx opnsense-mcp-server
   # Or if installed locally:
   node node_modules/opnsense-mcp-server/dist/index.js
   

4. Check Claude logs:

   • MacOS: ~/Library/Logs/Claude/
   • Windows: %APPDATA%\Claude\logs\
   • Linux: ~/.config/claude/logs/

Common Issues

• "command not found": Install globally with npm i -g opnsense-mcp-server or 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

• Documentation
• Examples
• Issues
• Discussions
• Model Context Protocol

Built with ❤️ for the MCP ecosystem