mcp-pfsense

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

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

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

Related MCP server: coreyhines/opnsense-mcp

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.

License

MIT