A Model Context Protocol (MCP) server implementation for managing OPNsense firewalls. This server allows Claude and other MCP-compatible clients to interact with all features exposed by the OPNsense API.
OPNsense® is a powerful open-source firewall and routing platform built on FreeBSD. Managing OPNsense typically involves using its web interface or interacting directly with its comprehensive API. This project offers a way to manage your OPNsense firewall using natural language through AI clients like Claude Desktop. It does this by providing a Python server application that implements Anthropic’s Model Context Protocol (MCP), a standard allowing AI models to securely connect to and utilize external tools. This locally running server listens for requests from MCP clients, translates them into the appropriate OPNsense API calls, and returns the results.
The Model Context Protocol (MCP) is a new standard that lets AI models (like Claude, ChatGPT, and others) securely interact with real-world tools, data, and systems—not just answer questions, but actually take action. You can think of it as “giving hands to the brain”: the AI is the brain, and the MCP server is the set of hands that can reach out and do things in the real world. For more technical details, refer to the official MCP specification.
MCP servers are a game changer because they let you safely delegate real-world tasks to AI, making your AI not just smart, but truly useful.
Below are some of the key features provided by this OPNsense MCP Server:
git (for cloning the repository)uv for Python package management (see installation below).jq (command-line JSON processor) if you plan to use the setup-claude.sh script for automated Claude Desktop configuration.Clone the Repository:
git clone https://github.com/floriangrousset/opnsense-mcp-server
cd opnsense-mcp-server
Install uv (if not already installed):
uv is a fast Python package installer and environment manager. Install it using the official instructions:
# For macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# For Windows (PowerShell)
curl -LsSf https://astral.sh/uv/install.ps1 | powershell -c -
Create and Activate Virtual Environment:
It’s highly recommended to use a virtual environment.
# Create a virtual environment
uv venv
# Activate it (Linux/macOS)
source .venv/bin/activate
# Activate it (Windows)
.venv\Scripts\activate
Install Dependencies:
uv pip install -r requirements.txt
Make Scripts Executable (Linux/macOS):
chmod +x opnsense-mcp-server.py
chmod +x setup-claude.sh
Before using this server, you need to create API credentials in your OPNsense firewall:
To use this MCP server with Claude Desktop, you can either configure it manually or use the provided setup script.
jq installed on your system. You can typically install it using your system’s package manager (e.g., apt install jq, yum install jq, brew install jq).chmod +x setup-claude.shbash setup-claude.shInstall Claude Desktop if you haven’t already
Open Claude Desktop
Access the settings from the Claude menu
Go to the Developer tab
Click on “Edit Config”
Find the mcpServers section (or add it if it doesn’t exist) and add the following entry:
{
"mcpServers": {
"opnsense": {
"command": "python",
"args": [
"/path/to/opnsense-mcp-server.py"
],
"env": {}
}
}
}
Replace /path/to/opnsense-mcp-server.py with the absolute path to your opnsense-mcp-server.py script.
Save the config file and restart Claude Desktop
Once the MCP server is configured and running with Claude Desktop, you can interact with your OPNsense firewall using natural language. Here are some examples:
Configure the connection to your OPNsense firewall:
Configure my OPNsense firewall with the following information:
URL: https://192.168.1.1
API Key: your_api_key
API Secret: your_api_secret
Check the system status:
What's the current status of my OPNsense firewall?
Manage firewall rules:
List all firewall rules.
Add a new firewall rule to allow HTTP traffic from any source to my web server at 192.168.1.100.
Delete the firewall rule with UUID abc123def456.
Work with firewall aliases:
Show me all the firewall aliases.
Add IP address 10.0.0.5 to the alias named "BlockedIPs".
Monitor network interfaces:
Show me all network interfaces and their status.
View system health:
What's the current health status of my OPNsense system? Show CPU, memory, and disk usage.
Manage services:
Restart the DHCP service.
Examine VPN connections:
Show me all active OpenVPN connections.
Execute a custom API call:
Execute a GET request to the endpoint "/interfaces/overview/interfacesInfo".
Perform a basic security audit:
Perform a security audit of my OPNsense firewall configuration.
Important: For maximum security in production environments, it is strongly recommended to adhere to strict management practices:
config.xml) and import it onto the production firewall (which could be running headless without GUI/API enabled).This MCP server provides powerful management capabilities but relies on the OPNsense API being enabled. Carefully evaluate the risks and benefits before enabling the API on critical production systems. Use dedicated, least-privilege API users and restrict access via firewall rules if the API must remain active.
If you encounter issues:
opnsense-mcp-server-logo.png and part of the project code was generated with the assistance of AI.Contributions are welcome! Please see the CONTRIBUTING.md file for guidelines on how to submit issues or pull requests.
This project is licensed under the MIT License - see the LICENSE file for details.