pfSense Enhanced MCP Server

A Model Context Protocol (MCP) server for managing pfSense firewalls through Claude Desktop, Claude Code, and other MCP-compatible clients. Verified against the pfSense REST API v2 PHP source code for production accuracy.

Supported pfSense Versions

Requires the pfSense REST API v2 package by jaredhendrickson13.

Related MCP server: MCP Server UniFi

Quick Start

1. Install pfSense REST API Package

SSH into your pfSense box and install the package for your version:

# pfSense CE 2.8.1
pkg-static add https://github.com/pfrest/pfSense-pkg-RESTAPI/releases/latest/download/pfSense-2.8.1-pkg-RESTAPI.pkg

# pfSense Plus 25.11
pkg-static -C /dev/null add https://github.com/pfrest/pfSense-pkg-RESTAPI/releases/latest/download/pfSense-25.11-pkg-RESTAPI.pkg

Then in the pfSense web UI: System > REST API to enable it, and System > User Manager > [your user] to generate an API key.

2. Setup MCP Server

git clone https://github.com/gensecaihq/pfsense-mcp-server.git
cd pfsense-mcp-server
pip install -r requirements.txt

cp .env.example .env
# Edit .env with your pfSense URL and API key

3. Configure Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "pfsense": {
      "command": "python",
      "args": ["-m", "src.main"],
      "cwd": "/path/to/pfsense-mcp-server",
      "env": {
        "PFSENSE_URL": "https://your-pfsense.local",
        "PFSENSE_API_KEY": "your-api-key",
        "PFSENSE_VERSION": "CE_2_8_0",
        "AUTH_METHOD": "api_key",
        "VERIFY_SSL": "true"
      }
    }
  }
}

4. Start the Server

# stdio mode (default — for Claude Desktop / Claude Code)
python -m src.main

# HTTP mode (for remote access, requires MCP_API_KEY for bearer auth)
python -m src.main -t streamable-http --port 3000

MCP Tools (41 total)

Firewall Rules (9 tools)

Aliases (5 tools)

NAT Port Forwards (4 tools)

DHCP (7 tools)

Services (2 tools)

Logs & Monitoring (3 tools)

System (4 tools)

Utility (7 tools)

API Endpoint Coverage

Not Yet Implemented

• Routing — static routes, gateways, gateway groups

• VPN — OpenVPN servers/clients, IPsec, WireGuard

• DNS — resolver/forwarder config, host overrides

• Certificates — CA, certificate, CSR management

• Users — user/group CRUD, LDAP/RADIUS

• NAT Outbound / 1:1 — outbound NAT rules

• Advanced — schedules, traffic shaper, virtual IPs

Architecture

src/
  main.py          Entry point (argparse, connection test, mcp.run())
  server.py        FastMCP instance + API client singleton
  client.py        HTTP client for pfSense REST API v2
  models.py        Enums, dataclasses (QueryFilter, SortOptions, etc.)
  helpers.py       Validation, pagination, safety guards
  middleware.py    Bearer auth middleware for HTTP transport
  tools/
    firewall.py    9 tools
    aliases.py     5 tools
    nat.py         4 tools
    dhcp.py        7 tools
    services.py    2 tools
    logs.py        3 tools
    system.py      4 tools
    utility.py     7 tools

Environment Variables

Docker

# Build
docker build -t pfsense-mcp .

# Run in stdio mode
docker run --rm -e PFSENSE_URL=https://pfsense.local -e PFSENSE_API_KEY=your-key pfsense-mcp

# Run in HTTP mode (docker-compose)
docker compose up

The docker-compose.yml runs in streamable-http mode on port 3000 with bearer auth.

Testing

# Run all 223 tests
python -m pytest tests/ -v

# With coverage
python -m pytest tests/ --cov=src --cov-report=term-missing

# Only tool tests
python -m pytest tests/tools/ -v

# Only client tests
python -m pytest tests/test_api_client.py -v

Safety Guards

• Page size capped at 200 — prevents pfSense PHP memory exhaustion

• Log lines capped at 50 — same reason

• Port format validation — rejects "53 853" which crashes the pf compiler

• IP validation — validates addresses before sending to API

• Log type allowlist — prevents path traversal via log endpoint

• Bearer auth required for HTTP transport mode (fail-closed)

• Control parameters in JSON body — verified against pfSense API PHP source

Known Limitations

• Firewall log API only exposes raw text field; per-field filtering is done client-side

• HATEOAS toggle is a global API setting, not per-request (the tools toggle a local session flag)

• pfSense object IDs are non-persistent array indices that change after deletions

• Log retrieval is capped at 50 lines per request to prevent PHP memory exhaustion

Community & Contributions

We Need Your Help!

This MCP server has been verified against the pfSense REST API v2 PHP source code, but real-world testing across diverse pfSense environments is essential. Whether you're a pfSense veteran, Python developer, or GenAI enthusiast, there are many ways to contribute.

How You Can Help

Testing & Feedback

• Test with your pfSense setup and report what works (and what doesn't)

• Share use cases — tell us how you're using the MCP tools

• Performance feedback across different network sizes

Bug Reports & Issues

• Open an issue with detailed reproduction steps

• Suggest new MCP tools or API integrations

• Help improve documentation based on real-world usage

Code Contributions

• Add tools for missing endpoint categories (VPN, routing, DNS, certificates)

• Add support for pfSense packages (Snort, Suricata, HAProxy)

• Improve test coverage for edge cases

• Performance optimizations

Documentation

• Real-world example prompts that work well with Claude

• Integration guides for other MCP clients

• Video tutorials for setup and usage

Getting Started as a Contributor

1. Fork the repository and create a feature branch

2. Run the test suite: python -m pytest tests/ -v

3. Update tests for any new features

4. Submit a pull request with a clear description

Ideas for Contributions

High Priority

• VPN status and configuration tools (OpenVPN, IPsec, WireGuard)

• Routing and gateway management

• DNS resolver/forwarder configuration

• Certificate management

Medium Priority

• Support for pfSense packages (Snort, ntopng, FreeRADIUS)

• Multi-pfSense instance management

• GraphQL API integration

• Enhanced log parsing and analysis

Stay Connected

• GitHub Issues: Report bugs and request features

• Pull Requests: Contribute code and documentation

• Releases: Follow for updates

License

MIT License — see LICENSE for details.

Acknowledgments

• jaredhendrickson13 / pfrest for the pfSense REST API v2 package

• JeremiahChurch for the production-tested modular rewrite (PR #5, 217 tests)

• shawnpetersen for discovering the correct API v2 endpoint paths (PR #3)

• Netgate for pfSense

• FastMCP for the MCP framework