pfSense MCP server for AI agents

The pfSense MCP Server enables natural language interaction with pfSense firewalls through Claude Desktop and other GenAI applications, allowing you to control and monitor your firewall using plain English commands instead of complex syntax.

Features

Natural language interface for controlling pfSense using plain English
Multiple access levels from read-only monitoring to emergency response
Support for REST API, XML-RPC, and SSH connection methods
Complete security operations coverage across six functional categories
Integration with Claude Desktop, Continue, and other MCP clients
Production-ready with audit logging, rate limiting, and caching

Installation

Prerequisites

Docker and Docker Compose (recommended)
Python (for local installation)
pfSense instance with API access

Docker Installation

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

# Copy environment template
cp .env.example .env

# Edit configuration file with your pfSense details
nano .env

After configuring your environment file, build and start the Docker container:

# Build and start
docker-compose up -d

# Verify the server is running
curl http://localhost:8000/health

Local Installation

If you prefer to run without Docker:

Clone the repository
Install dependencies (requirements.txt)
Configure environment variables
Run the server directly with Python

Configuration

Environment Variables

Configure your .env file with the following parameters:

PFSENSE_URL: URL of your pfSense instance
PFSENSE_API_KEY: Your pfSense API key
Additional connection parameters (username, password if using SSH)

Claude Desktop Configuration

Add the MCP server to your Claude Desktop configuration file:

{
  "mcpServers": {
    "pfsense": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--env-file", "/path/to/.env", "pfsense-mcp:latest"],
      "env": {
        "MCP_MODE": "stdio"
      }
    }
  }
}

For local installation:

{
  "mcpServers": {
    "pfsense": {
      "command": "python",
      "args": ["/path/to/pfsense-mcp-server/main.py"],
      "env": {
        "PFSENSE_URL": "https://your-pfsense.local",
        "PFSENSE_API_KEY": "your-api-key"
      }
    }
  }
}

Usage

Access Levels

The MCP server supports multiple access levels:

Level	Description	Example Users
`READ_ONLY`	Monitor and view	Security Analysts
`SECURITY_WRITE`	Modify security rules	Security Engineers
`ADMIN_WRITE`	Full system access	Administrators
`COMPLIANCE_READ`	Audit and compliance	Compliance Officers
`EMERGENCY_WRITE`	Emergency response	Incident Responders

Example Commands

You can interact with your pfSense firewall using natural language commands like:

"Show me the system status"
"What IPs are currently blocked?"
"Block IP 192.168.1.100"
"Run a PCI compliance check"
"Analyze threats from the last hour"
"EMERGENCY: Block all traffic from Russia"

Testing Connectivity

Test your connection to the pfSense server:

python scripts/test_connection.py

Token Generation

Generate authentication tokens with specific access levels:

python scripts/generate_token.py alice READ_ONLY

Troubleshooting

If you encounter issues:

Verify your pfSense URL and API key are correct
Check that your pfSense instance has API access enabled
Ensure required ports are open between your MCP server and pfSense
Check the logs for detailed error messages

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "pfsense" '{"command":"docker","args":["run","-i","--rm","--env-file","/path/to/.env","pfsense-mcp:latest"],"env":{"MCP_MODE":"stdio"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "pfsense": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "--env-file",
                "/path/to/.env",
                "pfsense-mcp:latest"
            ],
            "env": {
                "MCP_MODE": "stdio"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

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

2. Add this to your configuration file:

{
    "mcpServers": {
        "pfsense": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "--env-file",
                "/path/to/.env",
                "pfsense-mcp:latest"
            ],
            "env": {
                "MCP_MODE": "stdio"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect