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

Variable	Description	Required	Default
`OPNSENSE_HOST`	OPNsense URL (include https://)	Yes	-
`OPNSENSE_API_KEY`	API key from OPNsense	Yes	-
`OPNSENSE_API_SECRET`	API secret from OPNsense	Yes	-
`OPNSENSE_VERIFY_SSL`	Verify SSL certificates	No	`true`
`LOG_LEVEL`	Logging level	No	`info`
`CACHE_ENABLED`	Enable response caching	No	`true`
`CACHE_TTL`	Cache time-to-live in seconds	No	`300`

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

Enable API in OPNsense:
- Navigate to: System → Settings → Administration
- Check: "Enable API"
- Save
Create API credentials:
- Navigate to: System → Access → Users
- Edit user or create new
- Under "API Keys", click "+" to generate key/secret
- Save credentials securely
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:

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
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)
Test standalone first:
npx opnsense-mcp-server # Or if installed locally: node node_modules/opnsense-mcp-server/dist/index.js
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

Built with ❤️ for the MCP ecosystem

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,453
2,841
TypeScript
Apache 2.0
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 -
9
36
15
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 -
13
Python
MIT License
System Monitor MCP Server
PraveerT
-
security
F
license
-
quality
Provides system monitoring and management capabilities for Claude CLI, allowing users to view system information, track resource usage, and manage processes through natural language commands.
Last updated -
Python

View all related MCP servers