pfsense

This MCP server provides a natural language interface to manage pfSense via Claude Desktop and other GenAI apps. It exposes enhanced firewall management capabilities, advanced filtering, HATEOAS navigation, and enterprise-grade controls to interact with pfSense REST API v2. After starting the server, you can connect Claude or your preferred client to issue prompts like searching for firewall rules, querying logs, or configuring rules using natural language. The server translates natural language requests into pfSense API calls with support for fine-grained control parameters such as apply, async execution, and placement of firewall rules. With HATEOAS enabled, you can navigate available API actions dynamically via navigation links. The toolset includes discovery, rule management, monitoring, and object/id management utilities to streamline pfSense administration from conversational interfaces.

Prerequisites:

• Python 3.8+ and pip
• pfSense REST API package installed on your pfSense device (pfSense API v2)
• Internet access for package installation (or a local mirror)

Step-by-step installation:

# 1. Clone the repository
git clone https://github.com/gensecaihq/pfsense-mcp-server.git
cd pfsense-mcp-server

# 2. Set up a Python environment (recommended)
python3 -m venv venv
source venv/bin/activate  # on Unix/macOS
venv\Scripts\activate     # on Windows

# 3. Install Python dependencies
pip install -r requirements.txt

# 4. Configure environment (copy example and edit)
cp .env.example .env
nano .env  # fill in PFSENSE_URL, PFSENSE_API_KEY, PFSENSE_VERSION, etc.

Start the MCP server:

# Run the enhanced MCP server (example)
python -m src.main_enhanced_mcp  # or run the main_enhanced_mcp.py file directly as configured

Configuration tips:

• Ensure pfSense REST API is enabled and your API key has appropriate privileges.
• Set ENABLE_HATEOAS to true if you want hypermedia navigation links in responses.
• Verify SSL verification in environments with self-signed certificates and adjust VERIFY_SSL accordingly in your config.

Tips and common issues:

• If the server fails to connect to pfSense, double-check PFSENSE_URL, API key, and network connectivity from the MCP host.
• When ENABLE_HATEOAS is off, navigation links will be omitted; turn it on to explore the API via hypermedia controls.
• Some pfSense API endpoints may require elevated privileges; ensure the API key user has the necessary roles.
• For Claude Desktop integration, ensure the client configuration points to the correct Python command and script path, and that environment variables are correctly exported to the process.
• If you update pfSense versions, update PFSENSE_VERSION accordingly to match the supported REST API package.