pfSense MCP Server

Manage your pfSense firewall with natural language. 327 tools. 9 layers of safety. One command to start.

You: "Block all traffic from 203.0.113.5 on WAN"
Claude: Creates block rule → applies changes → confirms with rollback instructions

pfSense MCP Server connects Claude Desktop, Claude Code, and other MCP-compatible AI clients to your pfSense firewall. Ask questions, diagnose issues, and manage your firewall — all through conversation.

Why This Exists

Managing a pfSense firewall means clicking through web UI tabs, remembering field names, and hoping you don't fat-finger a rule that locks you out. With this MCP server, you describe what you want in plain English and the AI handles the REST API calls, validates inputs, and warns you before anything destructive happens.

What makes it different:

• Every destructive operation requires explicit confirmation and shows you exactly what will happen
• Automatic config backup before every delete/reboot — with a one-line rollback command
• Rate limiting prevents runaway AI loops from flooding your firewall with rules
• Input sanitization blocks command injection, path traversal, and XSS in every parameter

Quick Start

Prerequisites: Python 3.10+, pfSense with REST API v2 package installed

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: set PFSENSE_URL, AUTH_METHOD, and credentials

Connect to Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pfsense": {
      "command": "python3",
      "args": ["-m", "src.main"],
      "cwd": "/path/to/pfsense-mcp-server",
      "env": {
        "PFSENSE_URL": "https://192.168.1.1",
        "AUTH_METHOD": "basic",
        "PFSENSE_USERNAME": "admin",
        "PFSENSE_PASSWORD": "your-password",
        "PFSENSE_VERSION": "CE_2_8_0",
        "VERIFY_SSL": "false"
      }
    }
  }
}

Start talking to your firewall. Open Claude Desktop and ask:

• "Show me all blocked traffic in the last hour"
• "What services are running?"
• "Create a port forward for port 443 to 192.168.1.50"
• "Run a full system health check"

What You Can Do

327 tools across every major pfSense subsystem:

Safety First

AI managing a production firewall needs guardrails. This server has 9 layers:

"Delete firewall rule 5"

  1. CLASSIFY    → HIGH risk (destructive)
  2. ALLOWLIST   → tool is permitted
  3. SANITIZE    → parameters clean (no injection)
  4. RATE LIMIT  → under 10 deletes/minute
  5. DRY RUN?    → user can preview first
  6. CONFIRM     → blocked until confirm=True
  7. BACKUP      → config revision captured
  8. EXECUTE     → API call made
  9. AUDIT LOG   → action recorded with redacted params

Response includes:
  "config_backup": {
    "pre_change_revision_id": 42,
    "rollback_instruction": "restore_config_backup(revision_id=42, confirm=True)"
  }

Every destructive operation (52 delete/reboot/halt tools) requires confirm=True. Every create and update operation (112 tools) is rate-limited and sanitized. Every sensitive parameter (passwords, keys, tokens) is redacted in logs and outputs.

You can also:

• Pass dry_run=True to preview any destructive operation without executing
• Pass verify_descr="Allow HTTPS" to verify you're deleting the right rule (guards against ID shifts)
• Set MCP_READ_ONLY=true to expose only 118 read-only tools (search, get, diagnose)
• Set MCP_ALLOWED_TOOLS=search_firewall_rules,get_firewall_log to restrict to specific tools

Supported pfSense Versions

Requires the pfSense REST API v2 package by jaredhendrickson13.

Authentication

Three methods supported (configure in .env):

Deployment Options

stdio (default) — for Claude Desktop and Claude Code:

python3 -m src.main

HTTP — for remote access and multi-client setups:

python3 -m src.main -t streamable-http --port 3000

Docker — hardened container with read-only filesystem:

docker compose up

Container security: non-root user (mcp:1000), read-only filesystem, all capabilities dropped, noexec tmpfs, no-new-privileges.

Configuration

Testing

python3 -m pytest tests/ -v          # 308 tests
python3 -m pytest tests/ --cov=src   # with coverage

MCP Specification Compliance

Compliant with MCP 2025-11-25 (latest):

• ToolAnnotations on all 327 tools (readOnlyHint, destructiveHint, idempotentHint)
• serverInfo.version and instructions provided
• Origin header validation (MUST requirement)
• Bearer token auth with timing-safe comparison
• Default bind to localhost per spec SHOULD
• stdio and Streamable HTTP transports

Project Structure

src/
  main.py              Entry point
  server.py            FastMCP instance + API client
  client.py            pfSense REST API v2 HTTP client
  guardrails.py        9-layer defense-in-depth system
  helpers.py           Validation, parsing, safety guards
  models.py            Data models
  middleware.py        HTTP auth + Origin validation
  tools/               34 tool modules (327 tools)
tests/                 308 tests

Contributing

We need real-world testing across diverse pfSense environments. See CONTRIBUTING or:

1. Fork and create a feature branch
2. Run python3 -m pytest tests/ -v
3. Submit a PR

Ideas: integration tests against real pfSense, additional package support (Snort, Suricata), Ollama local LLM bridge, multi-instance management.

License

MIT

Acknowledgments

• jaredhendrickson13 / pfrest — pfSense REST API v2 package
• JeremiahChurch — modular rewrite (PR #5)
• shawnpetersen — API v2 endpoint discovery (PR #3)
• Netgate — pfSense
• FastMCP — MCP framework