A Model Context Protocol (MCP) server for managing OPNsense firewalls through Claude Desktop or Claude Code.

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"

• 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

• Node.js 18+
• OPNsense firewall with API access enabled
• Claude Desktop or Claude Code

# Use directly with npx - no installation needed
npx opnsense-mcp-server

# Or install globally
npm install -g opnsense-mcp-server

# Use latest from GitHub
npx github:vespo92/OPNSenseMCP

git clone https://github.com/vespo92/OPNSenseMCP
cd OPNSenseMCP
npm install
npm run build

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

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

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)

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

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!

• 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

"Create a guest network on VLAN 20 with internet access only"

"Show me all devices from Apple on my network"

"Block gambling and adult content sites"

"Configure HAProxy to load balance my web servers"

More examples in the examples/ directory.

npm run start:sse  # HTTP server on port 3000

Deploy entire network configurations declaratively. See IaC documentation.

Build reusable network templates. See pattern examples.

We welcome contributions! Please see our Contributing Guide for details.

npm install
npm run dev  # Development mode with hot reload

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/

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

MIT License - see LICENSE for details.

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

Built with ❤️ for the MCP ecosystem