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.

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.

What it does

• 97 tools: 95 pfSense READ tools + 2 documentation guidance tools. 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-change path exists but requires an explicit opt-in — see Safety levels below.
• 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.

Quick start

pipx install pfsense-mcp-server
pfsense-mcp-security setup

(If you arrived here from PyPI's own generic "pip install" box above — that's PyPI's fixed page header, not this project's recommendation. Use the pipx command shown here instead.)

No pipx yet? sudo apt install pipx && pipx ensurepath on Debian/Ubuntu (reopen your terminal afterward) — see Installation for other platforms and a plain virtual-environment alternative. A system-wide pip install is deliberately not the recommended path: on modern Debian/Ubuntu it's refused outright (PEP 668), and even where it isn't, it risks touching packages your OS itself depends on.

The setup wizard asks a few plain-language questions — your firewall's address, whether to allow read-only or protected changes, how to verify the connection — then prints the exact configuration to paste into your MCP client. Nothing needs to be typed or edited by hand. Prefer to configure manually, or want the full walkthrough step by step? See Getting started.

Once your client is connected and shows 97 tools available, try one of the questions from What it does above.

Safety levels

Choose the level that matches what you need — you can change this later by running setup again.

No level silently escalates into another, and nothing above read-only is reachable unless you explicitly opt in during setup. Exact internal mechanics — plan digests, authorization tokens, the sealed mutation executor, witness state — are documented in full for advanced users and auditors in the Security model.

Architecture at a glance

AI client (Claude, Codex, ...)
  │  MCP over stdio
  ▼
pfsense-mcp-server
  │  one typed method call, GET-only
  ▼
pfSense's pfREST API
  │
  ▼
pfSense appliance

Every one of the 95 READ tools takes this exact path, no exceptions — enforced mechanically at build time, not just by convention (a make validate check requires exactly one typed client call per READ tool, structurally preventing a tool/endpoint mismatch).

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

A fully built, twice live-verified path exists for exactly one protected-change operation (a firewall alias's description field) but stays unreachable unless you explicitly opt in during setup: 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.

What you get

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

Connect your MCP client

For Claude Desktop and Codex CLI / ChatGPT desktop, 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

This previews the change and asks for explicit confirmation before writing anything — it never silently overwrites an existing config. Every other supported client — Claude Code, Cursor, VS Code, Continue, and any other MCP-compatible client — has its own copy/paste-ready guide instead of a generator. Ready-made per-client guides — examples/README.md. Full detail: Connect your MCP client.

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.

Documentation

Getting started Installation · Security setup wizard · Connect your MCP client

Using the server MCP tool reference · Tool & guidance reference · Configuration reference

Security Security model · Threat model · Tier 1 safety architecture

Reference Compatibility · Architecture diagrams · Public roadmap

Developer / contributor Architecture decisions · Contributing · Support · Security policy

Release status

v0.9.0 is the immutable production baseline, published on PyPI — 95 pfSense READ tools + 2 documentation guidance tools, 0 WRITE tools. pfsense_get_api_guidance covers the community-maintained pfREST package (pfSense-pkg-RESTAPI, documented at pfrest.org), kept structurally separate from pfsense_get_official_guidance (Netgate product documentation) — never blended. Evidence is explicitly labeled by provenance (PROJECT_AUTHORED / PFREST_UPSTREAM / LIVE_APPLIANCE_SCHEMA / OFFICIAL_NETGATE); documentation is data, never authority. See CHANGELOG.md's [0.9.0] entry and docs/ACCEPTANCE_v0.9.0.md for the complete, independently verified evidence — 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.

pfSense® is a registered trademark of Electric Sheep Fencing, LLC, exclusively licensed to Rubicon Communications, LLC d/b/a Netgate. This project is an independent, community-built tool. It is not affiliated with, endorsed by, or sponsored by Electric Sheep Fencing, LLC or Netgate.