pfsense-mcp-server

Safe, least-privilege pfSense access for AI assistants. MCP server that gives an AI assistant strongly typed, read-only visibility into one pfSense appliance — system, network, firewall, DHCP, DNS, VPN, certificates, and diagnostics — without raw shell access, an unaudited scripting surface, or any way to change the appliance by accident.

What it does

• 95 public READ tools + 1 documentation guidance tool. Covers roughly 90% of pfSense's useful REST API READ surface. Every tool is strongly typed (Pydantic) — no untyped JSON passthrough.
• 0 WRITE tools by default. A fully built, twice live-verified protected-WRITE path exists but requires an explicit operator opt-in — see Safety by default.
• Ask it things like: "List my VLANs and which interface each one rides on," "Is my WAN gateway up right now?", "Which certificates expire soon?", "What DHCP leases are active on the LAN?" — every question maps to one typed, capability-gated tool.

Safety by default

• READ-oriented public MCP surface, 0 default-reachable WRITE. Enforced by an automated snapshot test, not just documented — a change to the public tool contract that isn't reflected in the approved snapshot fails CI.
• Explicit tool registration, never generic API dispatch. There is no call_endpoint(path, method) escape hatch an AI (or a bug) could use to reach an unregistered endpoint.
• Capability-based least privilege, with secret-bearing fields excluded from the response model by construction wherever confirmed present — never relying on the upstream API's own redaction alone.
• Guidance is data, never authority. The one documentation-guidance tool structurally cannot influence, select, or authorize any action — see Tool & guidance reference.

I built this because I wanted AI assistance for pfSense without giving an LLM the ability to accidentally disconnect my own network — a firewall deserves a higher safety standard than "the model probably won't make a bad change." See Why this project exists for the full reasoning.

Every one of the 95 READ tools takes this same path — no exceptions.

The protected-WRITE path (built, not default-reachable)

A fully built, twice live-verified WRITE architecture exists for exactly one operation (a firewall alias's description field) but stays unreachable unless an operator explicitly opts in: write_protected must be selected, an off-host Ed25519 signature the running server never holds the key for must authorize it, and a separate confirmation authority must confirm it — see the security setup wizard and the security model for exactly what it requires and does not do by default.

See the full architecture diagrams page for the gate-by-gate detail behind both diagrams above.

Requirements

• Python 3.11, 3.12, or 3.13.
• pfSense with the REST API package (pfrest/pfSense-pkg-RESTAPI, API v2) installed and enabled.

See Compatibility for exactly which pfSense editions/releases are directly verified vs. merely expected to work.

Quick start

python -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install --upgrade pfsense-mcp-server
install -m 600 /dev/null /absolute/private/path/pfsense-api.key
# paste your pfSense API key as the file's first line, then:

{
  "command": "/absolute/path/to/.venv/bin/pfsense-mcp-server",
  "env": {
    "PFSENSE_API_URL": "https://pfsense.example.invalid",
    "PFSENSE_IDENTITY": "api-mcp-admin",
    "PFSENSE_API_KEY_FILE": "/absolute/private/path/pfsense-api.key",
    "PFSENSE_TLS_MODE": "strict"
  }
}

Point your MCP client at that command (see Connect your MCP client below), confirm it shows 96 tools (95 READ + 1 guidance, 0 WRITE), then try one of the prompts from What it does above. Full walkthrough, credential handling, and verification steps: Installation.

First setup

Prefer a dedicated, least-privilege pfSense identity over reusing an existing credential? The bundled operator CLI can provision and verify one for you:

pfsense-mcp-security setup

This is a guided, non-mutating wizard — it only plans; nothing is provisioned until a separate, explicit setup apply step with a confirmation token you've reviewed. Full walkthrough, including the optional protected-WRITE opt-in: Security setup wizard.

Connect your MCP client

Once your server configuration works, generate the exact client config block automatically:

pfsense-mcp-security setup write-client-config \
  --client claude-desktop --config-path /absolute/path/to/claude_desktop_config.json \
  --capability-posture read_only --anchor-assurance none

Or copy one of the ready-made per-client guides — Claude Desktop, Claude Code, Codex CLI, ChatGPT desktop, Cursor, VS Code, Continue — from examples/README.md. Full detail on both paths: Connect your MCP client.

What you get

Full per-tool reference, parameters, and provenance: MCP tool reference · Tool & guidance reference.

Documentation

• Installation · Compatibility
• Security setup wizard · Connect your MCP client
• Configuration reference (env vars, troubleshooting)
• MCP tool reference · Tool & guidance reference
• Security model · Threat model
• Architecture diagrams · Architecture decisions
• Tier 1 safety architecture · Public roadmap
• Contributing · Support · Security policy

Release status

v0.8.0 is the immutable production baseline, published on PyPI — 95 pfSense READ tools + 1 official-guidance tool, 0 WRITE tools. A CLI-only expansion of the pfsense-mcp-security operator tooling (ADR-021/ADR-033) over v0.7.2 — no MCP capability change, public contract byte-identical to v0.7.2. Adds the pfsense-mcp-security recover CLI subcommand and the full guided setup/setup apply/setup write-client-config provisioning wizard, plus a restart-classification correctness fix for bootstrap. See CHANGELOG.md's [0.8.0] entry and docs/ACCEPTANCE_v0.8.0.md for the complete, independently verified evidence, and CHANGELOG.md in full for every prior release's own complete history — every past release's tag, GitHub Release, and PyPI artifact remains unmoved as an accurate historical record.

Contributing

Contributions are welcome within the documented security and approval boundaries. Read CONTRIBUTING.md before opening a change.

License

Licensed under the MIT License.