mcp-pfsense

Read-only MCP server for the pfSense REST API (community package pfSense-pkg-RESTAPI).

Scope is intentional and finished: GET-only tools, aggressive secret redaction, least-privilege API key. There is no roadmap to add write/mutate operations. If you need an agent that changes firewall rules, VPN, DHCP, or DNS, use a different project (see Alternatives).

Designed for local MCP clients against a pfSense box reached over a private network (VPN / reverse proxy recommended).

When to use this

• You want structured, current pfSense state in an MCP client (Cursor, Claude Desktop, Codex, …).

• You want a hard read-only boundary (HTTP client cannot issue non-GET; no write tools registered).

• You accept a small fixed tool catalog instead of hundreds of mutate endpoints.

When not to: if your agent already has a shell and you can call pfrest with env-backed wrappers / curl, that is often simpler and more flexible than maintaining an MCP server. Prefer that when the goal is personal automation, not a shared MCP tool surface.

Related MCP server: io.github.antonio-mello-ai/mcp-pfsense

Features

• API key auth (X-API-Key)

• HTTP client that only issues GET

• Aggressive secret redaction (WireGuard keys, passwords, bcrypt hashes…)

• Tools: system, interfaces, gateways, firewall, aliases, NAT, DHCP, DNS, WireGuard, ARP

Requirements

• Python 3.11+

• Poetry

• pfSense CE with pfSense-pkg-RESTAPI ≥ v2.9.0 installed (see SETUP.md)

• Network path to the webGUI API (VPN + private reverse proxy recommended)

Setup

cp .env.example .env   # set PFSENSE_URL, PFSENSE_API_KEY
poetry install

See SETUP.md for creating user mcp and a read-only API key.

Run (stdio)

poetry run mcp-pfsense

MCP client config

Point your client at the in-project Poetry venv (after poetry install with virtualenvs.in-project = true):

{
  "mcpServers": {
    "pfsense": {
      "command": "/absolute/path/to/mcp-pfsense/.venv/bin/python",
      "args": ["-m", "mcp_pfsense"],
      "envFile": "/absolute/path/to/mcp-pfsense/.env"
    }
  }
}

On Windows, use .venv\\Scripts\\python.exe instead of .venv/bin/python.

Works the same way for Cursor, Claude Desktop, Codex, or any stdio MCP client.

Inspector

npx @modelcontextprotocol/inspector poetry run mcp-pfsense

Connectivity check

poetry run mcp-pfsense-check
poetry run mcp-pfsense-check --check-write-denied   # optional ACL probe

Tests

poetry run pytest
poetry run ruff check .
poetry run ruff format --check .

Env vars

Security model

• The HTTP wrapper exposes only GET; non-GET methods are not available on the client.

• Responses are recursively redacted for known secret keys (WireGuard private/preshared keys, passwords, bcrypt hashes, …).

• Prefer three locks: package Read only, a GET-only user, and this GET-only client.

• Do not expose the pfSense webGUI on the WAN; reach it over VPN or a private reverse proxy.

Alternatives

• Shell + API (often better for personal use): env file + GET-only curl / small wrappers. More flexible path coverage; no MCP process to maintain. Secrets stay in the environment instead of a separate MCP config if you already work that way.

• Write / manage pfSense: gensecaihq/pfsense-mcp-server — broad pfrest MCP surface with mutate tools and safety guardrails. Prefer that (or pfrest directly) if you need changes, not just inventory.

This repo stays read-only on purpose.

License

MIT