Skip to content
Back to search

pfsense-mcp-server

Model Context Protocol (MCP) server for pfSense firewall management. Control firewall rules, VPNs, DNS, DHCP and diagnostics in natural language from Claude Desktop, Claude Code or any MCP client — 333 wire-format-verified tools for the pfSense REST API, with safety guardrails, config backup and rollback on every change.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gensecaihq--pfsense-mcp-server/badge.svg)](/listings/gensecaihq--pfsense-mcp-server)

HTML

<a href="/listings/gensecaihq--pfsense-mcp-server"><img src="/api/listings/gensecaihq--pfsense-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Prerequisites:** - Python 3.11 or later. - pfSense with the [REST API v2 package](https://github.com/pfrest/pfSense-pkg-RESTAPI) installed. See [Supported pfSense versions](#supported-pfsense-versions). - For Option A, [uv](https://docs.astral.sh/uv/).

> [!IMPORTANT] > This project is **not published on PyPI**. A different, unrelated project uses the PyPI name `pfsense-mcp-server`, so never run `pip install pfsense-mcp-server`. Install from Git or from the [release assets](https://github.com/gensecaihq/pfsense-mcp-server/releases/latest) as shown below.

**Option A: run without cloning (uvx):**

uvx --from git+https://github.com/gensecaihq/pfsense-mcp-server@v1.1.0 pfsense-mcp-server

**Option B: clone for development:**

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 the server to `claude_desktop_config.json`: - macOS: `~/Library/Application Support/Claude/` - Windows: `%APPDATA%\Claude\`

Using the installed entry point (Option A):

{
  "mcpServers": {
    "pfsense": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/gensecaihq/pfsense-mcp-server@v1.1.0", "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_1",
        "PFSENSE_CA_FILE": "/path/to/pfsense-ca.pem"
      }
    }
  }
}

Or running from a clone (Option B):

{
  "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_1",
        "PFSENSE_CA_FILE": "/path/to/pfsense-ca.pem"
      }
    }
  }
}

Remove `PFSENSE_CA_FILE` if your pfSense certificate is signed by a public CA.

**About the CA file.** pfSense ships with a self-signed certificate from its own CA, and Python does not read your OS trust store, so verification fails out of the box. Export the CA at **System > Cert. Manager > CAs** (the export-certificate icon), save the PEM anywhere readable, and point `PFSENSE_CA_FILE` at it. A missing or unparseable file is a startup error, never a silent downgrade.

`VERIFY_SSL=false` also connects, and is fine for a throwaway lab. Understand what it costs: nothing authenticates the firewall, so anything that can intercept the connection can read the API key and act as the firewall. This tool changes firewall rules — treat that credential accordingly.

**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 was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 481 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # 🛡️ pfSense MCP Server
  3. ### Manage your pfSense firewall in plain English — from Claude Desktop, Claude Code, or any MCP client.
  4. **332 tools** across every subsystem · **wire-format verified** against the pfSense REST API · **safety guardrails** on every change
  5. <br>
  6. [![Release](https://img.shields.io/github/v/release/gensecaihq/pfsense-mcp-server?label=release)](https://github.com/gensecaihq/pfsense-mcp-server/releases/latest)
  7. [![CI](https://github.com/gensecaihq/pfsense-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/gensecaihq/pfsense-mcp-server/actions/workflows/ci.yml)
  8. [![MCP 2025-11-25](https://img.shields.io/badge/MCP-2025--11--25-6E56CF.svg)](https://modelcontextprotocol.io)
  9. [![pfSense API v2.10.2](https://img.shields.io/badge/pfSense%20API-v2.10.2-orange.svg)](https://pfrest.org/)
  10. [![Python 3.11–3.13](https://img.shields.io/badge/python-3.11%20|%203.12%20|%203.13-3776AB.svg)](https://www.python.org/)
  11. [![Tests](https://img.shields.io/badge/tests-661%20passing-brightgreen.svg)](#testing)
  12. [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
  13. [![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
  14. </div>
  15. ---
  16. ```text
  17. You: Block all traffic from 203.0.113.5 on WAN
  18. Claude: ✓ created block rule → ✓ applied changes → rollback point: config revision 42
  19. You: Why can't 192.168.1.50 reach the internet?
  20. Claude: ran diagnostics → gateway WAN_DHCP is down, and a block rule on LAN matches this host
  21. You: Add a WireGuard peer for my laptop and show me the config
  22. Claude: ✓ created peer on tun_wg0 → here's the client config to import
  23. ```
  24. **pfSense MCP Server** connects [Claude Desktop](https://claude.ai/download), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), and any other [MCP](https://modelcontextprotocol.io) client to your pfSense firewall. Ask questions, diagnose issues, and change configuration through conversation. Every destructive action needs explicit confirmation, and the server records the config revision it can be rolled back to.
  25. Letting an AI change a production firewall is only safe if the details are right, and that's where the work went:
  26. - A contract-test layer checks every tool's request format against the pfSense REST API schema.
  27. - Every change goes through a multi-layer guardrail pipeline.
  28. - CI runs 661 tests on Python 3.11–3.13, plus an end-to-end MCP protocol test.
  29. **Latest release: [v1.1.0](https://github.com/gensecaihq/pfsense-mcp-server/releases/tag/v1.1.0)** · [Changelog](CHANGELOG.md)
  30. > [!TIP]
  31. > Jump to the [Quick Start](#quick-start). Setup takes about two minutes with `uvx`, and you don't need to clone anything. If this project is useful to you, a ⭐ helps others find it.
  32. ## Contents
  33. [Why this exists](#why-this-exists) ·
  34. [Quick start](#quick-start) ·
  35. [What you can do](#what-you-can-do) ·
  36. [Safety](#safety-first) ·
  37. [Supported versions](#supported-pfsense-versions) ·
  38. [Authentication](#authentication) ·
  39. [Deployment](#deployment-options) ·
  40. [Configuration](#configuration) ·
  41. [Testing](#testing) ·
  42. [MCP compliance](#mcp-specification-compliance) ·
  43. [Known limitations](#known-limitations) ·
  44. [Architecture](ARCHITECTURE.md) ·
  45. [Contributing](CONTRIBUTING.md)
  46. ## Why This Exists
  47. 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.
  48. **What makes it different:**
  49. - Every destructive operation requires explicit confirmation and shows you exactly what will happen
  50. - The config revision is captured before every high-risk change. The response gives the revision ID to restore from **Diagnostics › Backup & Restore › Config History** in the webGUI, or warns explicitly if no revision could be captured.
  51. - Rate limits on every tool that changes configuration stop a runaway AI loop from flooding your firewall
  52. - Positive input validation (IP/port/MAC/CIDR) plus path-traversal/XSS screening, and secrets redacted from logs *and* API error responses
  53. - Wire-format verified against the pfSense REST API v2.10.2 schema by a contract-test layer, so tools send exactly what the API expects
  54. ## Quick Start
  55. **Prerequisites:**
  56. - Python 3.11 or later.
  57. - pfSense with the [REST API v2 package](https://github.com/pfrest/pfSense-pkg-RESTAPI) installed. See [Supported pfSense versions](#supported-pfsense-versions).
  58. - For Option A, [uv](https://docs.astral.sh/uv/).
  59. > [!IMPORTANT]
  60. > This project is **not published on PyPI**. A different, unrelated project uses the PyPI name `pfsense-mcp-server`, so never run `pip install pfsense-mcp-server`. Install from Git or from the [release assets](https://github.com/gensecaihq/pfsense-mcp-server/releases/latest) as shown below.
  61. **Option A: run without cloning (uvx):**
  62. ```bash
  63. uvx --from git+https://github.com/gensecaihq/pfsense-mcp-server@v1.1.0 pfsense-mcp-server
  64. ```
  65. **Option B: clone for development:**
  66. ```bash
  67. git clone https://github.com/gensecaihq/pfsense-mcp-server.git
  68. cd pfsense-mcp-server
  69. pip install -r requirements.txt
  70. cp .env.example .env
  71. # Edit .env: set PFSENSE_URL, AUTH_METHOD, and credentials
  72. ```
  73. **Connect to Claude Desktop.** Add the server to `claude_desktop_config.json`:
  74. - macOS: `~/Library/Application Support/Claude/`
  75. - Windows: `%APPDATA%\Claude\`
  76. Using the installed entry point (Option A):
  77. ```json
  78. {
  79. "mcpServers": {
  80. "pfsense": {
  81. "command": "uvx",
  82. "args": ["--from", "git+https://github.com/gensecaihq/pfsense-mcp-server@v1.1.0", "pfsense-mcp-server"],
  83. "env": {
  84. "PFSENSE_URL": "https://192.168.1.1",
  85. "AUTH_METHOD": "basic",
  86. "PFSENSE_USERNAME": "admin",
  87. "PFSENSE_PASSWORD": "your-password",
  88. "PFSENSE_VERSION": "CE_2_8_1",
  89. "PFSENSE_CA_FILE": "/path/to/pfsense-ca.pem"
  90. }
  91. }
  92. }
  93. }
  94. ```
  95. Or running from a clone (Option B):
  96. ```json
  97. {
  98. "mcpServers": {
  99. "pfsense": {
  100. "command": "python3",
  101. "args": ["-m", "src.main"],
  102. "cwd": "/path/to/pfsense-mcp-server",
  103. "env": {
  104. "PFSENSE_URL": "https://192.168.1.1",
  105. "AUTH_METHOD": "basic",
  106. "PFSENSE_USERNAME": "admin",
  107. "PFSENSE_PASSWORD": "your-password",
  108. "PFSENSE_VERSION": "CE_2_8_1",
  109. "PFSENSE_CA_FILE": "/path/to/pfsense-ca.pem"
  110. }
  111. }
  112. }
  113. }
  114. ```
  115. Remove `PFSENSE_CA_FILE` if your pfSense certificate is signed by a public CA.
  116. **About the CA file.** pfSense ships with a self-signed certificate from its own
  117. CA, and Python does not read your OS trust store, so verification fails out of
  118. the box. Export the CA at **System > Cert. Manager > CAs** (the export-certificate
  119. icon), save the PEM anywhere readable, and point `PFSENSE_CA_FILE` at it. A
  120. missing or unparseable file is a startup error, never a silent downgrade.
  121. `VERIFY_SSL=false` also connects, and is fine for a throwaway lab. Understand what
  122. it costs: nothing authenticates the firewall, so anything that can intercept the
  123. connection can read the API key and act as the firewall. This tool changes
  124. firewall rules — treat that credential accordingly.
  125. **Start talking to your firewall.** Open Claude Desktop and ask:
  126. - *"Show me all blocked traffic in the last hour"*
  127. - *"What services are running?"*
  128. - *"Create a port forward for port 443 to 192.168.1.50"*
  129. - *"Run a full system health check"*
  130. ## What You Can Do
  131. 332 tools across every major pfSense subsystem:
  132. | Domain | Tools | What You Can Do |
  133. |---|:---:|---|
  134. | **Firewall Rules** | 9 | Create, update, delete, reorder rules. Bulk block IPs. View compiled pf ruleset. |
  135. | **Aliases** | 5 | Manage host/network/port/URL aliases. Add and remove addresses. |
  136. | **NAT** | 16 | Port forwards, outbound NAT, 1:1 NAT — full lifecycle management. |
  137. | **VPN** | 51 | OpenVPN servers and clients, IPsec tunnels, WireGuard peers — CRUD, status, apply. |
  138. | **Routing** | 16 | Gateways, gateway groups, static routes, default gateway management. |
  139. | **DNS** | 23 | Unbound resolver and dnsmasq forwarder: host overrides, domain overrides, access lists. |
  140. | **DHCP** | 17 | Leases, static mappings, address pools, custom options, server config. |
  141. | **Certificates** | 15 | Certs, CAs, CRLs — generate, renew, export PKCS12. |
  142. | **Users** | 12 | User accounts, groups, LDAP/RADIUS auth server config. |
  143. | **Interfaces** | 14 | Interface config, VLANs, bridges, groups. |
  144. | **System** | 43 | Status, settings, diagnostics, state table, config history, reboot, ping. |
  145. | **Services** | 14 | Start/stop/restart services. NTP, cron, SSH, service watchdog. |
  146. | **Logs** | 4 | Firewall log analysis with parsed IPv4/IPv6 filterlog data. Raw tail/grep reads of the dhcpd/filter/resolver/system/auth log files. |
  147. | **Traffic Shaping** | 12 | Shapers, queues, and limiters for bandwidth management. |
  148. | **Schedules** | 8 | Time-based firewall rule scheduling. |
  149. | **Virtual IPs** | 5 | CARP, ProxyARP, and IP Alias management. |
  150. | **Troubleshooting** | 10 | Diagnose connectivity, blocked traffic, VPN, DHCP, DNS, HA. Full health report. |
  151. | **Packages** | 49 | HAProxy, ACME/Let's Encrypt, BIND DNS, FreeRADIUS. |
  152. | **Utility** | 9 | HATEOAS navigation, object ID management, guardrail status. |
  153. ## Safety First
  154. AI managing a production firewall needs guardrails. This server has 9 layers:
  155. ```
  156. "Delete firewall rule 5"
  157. 1. CLASSIFY → HIGH risk (destructive)
  158. 2. ALLOWLIST → tool is permitted
  159. 3. SANITIZE → parameters clean (no injection)
  160. 4. RATE LIMIT → under 10 deletes/minute
  161. 5. DRY RUN? → user can preview first
  162. 6. CONFIRM → blocked until confirm=True
  163. 7. BACKUP → config revision captured
  164. 8. EXECUTE → API call made
  165. 9. AUDIT LOG → action recorded with redacted params
  166. Response includes:
  167. "config_backup": {
  168. "pre_change_revision_id": 42,
  169. "rollback_instruction": "To undo this change, restore revision 42 manually in the pfSense webGUI: Diagnostics > Backup & Restore > Config History."
  170. }
  171. ```
  172. All 201 tools that change configuration carry a guardrail, and a test fails the build if a new one ships without it.
  173. - **Every change tool** is rate-limited, audit-logged and checked against the allowlist.
  174. - **High-risk tools (51):** deletes, disconnects, reboot, halt and bulk block are also blocked until the caller passes `confirm=True`.
  175. - **`manage_*` tools:** these require `confirm=True` for their remove and delete actions.
  176. - **Secrets:** passwords, keys, PSKs, bind passwords and tokens are redacted in the audit log **and** in echoed API error responses.
  177. `confirm=True` is a parameter the MCP client sends. It is not a separate human-approval step, so keep your client's tool-approval prompts on for destructive tools.
  178. You can also:
  179. - Pass `dry_run=True` to preview any destructive operation without running it.
  180. - Pass `verify_descr="Allow HTTPS"` to check that you're changing or deleting the rule you expect. This guards against rule IDs shifting.
  181. - Set `MCP_READ_ONLY=true` to expose only the 131 read-only tools (search, get, diagnose).
  182. - Set `MCP_ALLOWED_TOOLS=create_firewall_rule_advanced,delete_firewall_rule` to permit only the listed write tools. Read tools stay available.
  183. See [SECURITY.md](SECURITY.md) for the vulnerability-disclosure policy and deployment-hardening guidance.
  184. ## Supported pfSense Versions
  185. | Version | REST API package | Status |
  186. |---|---|---|
  187. | pfSense CE 2.9.0 | [v2.10.2](https://github.com/pfrest/pfSense-pkg-RESTAPI/releases/tag/v2.10.2) (latest) | Supported |
  188. | pfSense CE 2.8.1 | [v2.10.2](https://github.com/pfrest/pfSense-pkg-RESTAPI/releases/tag/v2.10.2) (latest) | Verified |
  189. | pfSense Plus 26.07 | [v2.10.2](https://github.com/pfrest/pfSense-pkg-RESTAPI/releases/tag/v2.10.2) (latest) | Supported |
  190. | pfSense Plus 26.03.1 | [v2.10.2](https://github.com/pfrest/pfSense-pkg-RESTAPI/releases/tag/v2.10.2) (latest) | Supported |
  191. | pfSense Plus 26.03 | [v2.10.2](https://github.com/pfrest/pfSense-pkg-RESTAPI/releases/tag/v2.10.2) (latest) | Verified |
  192. | pfSense Plus 25.11.1 | [v2.10.2](https://github.com/pfrest/pfSense-pkg-RESTAPI/releases/tag/v2.10.2) (latest) | Supported |
  193. | pfSense Plus 25.11 | [v2.7.3](https://github.com/pfrest/pfSense-pkg-RESTAPI/releases/tag/v2.7.3) (legacy) | Verified |
  194. | pfSense CE 2.8.0 | [v2.7.3](https://github.com/pfrest/pfSense-pkg-RESTAPI/releases/tag/v2.7.3) (legacy) | Supported |
  195. | pfSense Plus 24.11 | [v2.7.3](https://github.com/pfrest/pfSense-pkg-RESTAPI/releases/tag/v2.7.3) (legacy) | Supported |
  196. Requires the [pfSense REST API v2 package](https://github.com/pfrest/pfSense-pkg-RESTAPI) by [jaredhendrickson13](https://github.com/jaredhendrickson13). Package v2.8.x+ ships builds only for CE 2.8.1 and Plus 25.11.1/26.03/26.03.1; CE 2.9.0 and Plus 26.07 need v2.10.1+; v2.7.3 is the last release with builds for CE 2.8.0 and Plus 24.11/25.11.
  197. > **Security note:** run REST API package **v2.10.0+**. It fixes a command-injection
  198. > flaw in the interface-group endpoints
  199. > ([GHSA-w3w4-mvcc-vmgr](https://github.com/pfrest/pfSense-pkg-RESTAPI/security/advisories/GHSA-w3w4-mvcc-vmgr))
  200. > and adds core command auto-escaping; v2.9.0 fixed an earlier settings-sync
  201. > privilege escalation ([GHSA-8q8g-9f77-8g8g](https://github.com/pfrest/pfSense-pkg-RESTAPI/security/advisories/GHSA-8q8g-9f77-8g8g)).
  202. >
  203. > v2.10.0 also marks `OpenVPNClient.auth_pass`, `User.ipsecpsk`, and
  204. > `WireGuardPeer.presharedkey` as **sensitive**, so the API no longer returns
  205. > them by default. This server still *sets* them normally; if a workflow needs
  206. > to read one back, add a sensitive-field override in the REST API settings.
  207. ## Authentication
  208. Three methods supported (configure in `.env`):
  209. | Method | Config | Best For |
  210. |---|---|---|
  211. | **Basic Auth** | `AUTH_METHOD=basic` + username/password | Quick setup, local users |
  212. | **API Key** | `AUTH_METHOD=api_key` + key from System > REST API > Keys | Automation, service accounts |
  213. | **JWT** | `AUTH_METHOD=jwt` + username/password | Short-lived tokens, obtained and renewed automatically (assumes pfSense's default 1-hour lifetime) |
  214. ## Deployment Options
  215. **stdio** (default) — for Claude Desktop and Claude Code:
  216. ```bash
  217. python3 -m src.main # from a clone
  218. pfsense-mcp-server # via the installed console entry point (pip/uvx/pipx)
  219. ```
  220. **HTTP**: for remote access and multi-client setups. It requires `MCP_API_KEY`, and the server refuses to start with an empty, placeholder or short token.
  221. ```bash
  222. export MCP_API_KEY="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"
  223. python3 -m src.main -t streamable-http --port 3000
  224. ```
  225. The HTTP transport is plain HTTP. Put it behind a TLS-terminating reverse proxy before exposing it beyond localhost.
  226. **Docker**: a hardened container running the HTTP transport.
  227. ```bash
  228. cp .env.example .env # set PFSENSE_URL, credentials, and MCP_API_KEY
  229. docker compose up -d
  230. ```
  231. The published port binds to `127.0.0.1` by default. Set `MCP_BIND_ADDR=0.0.0.0` to expose it, but only behind TLS. For a private CA, put the PEM in `./certs/` and set `PFSENSE_CA_FILE=/certs/<file>.pem`.
  232. Container security:
  233. - Runs as a non-root user (`mcp:1000`).
  234. - Read-only filesystem, a `noexec` tmpfs, and `no-new-privileges`.
  235. - All Linux capabilities dropped.
  236. The health check probes an unauthenticated `/health` endpoint, because `/mcp` requires the bearer token.
  237. **Behind an MCP gateway** — the HTTP transport is a spec-compliant Streamable
  238. HTTP endpoint with bearer-token auth, so it can be registered as an MCP-server
  239. target behind managed gateways such as
  240. [AWS Bedrock AgentCore Gateway](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-MCPservers.html)
  241. (use its API-key credential provider to supply the `MCP_API_KEY` bearer token,
  242. and add the gateway's origin to `MCP_ALLOWED_ORIGINS`). Such gateways add
  243. centralized OAuth/IAM in front and translate between protocol revisions,
  244. including 2026-07-28. No gateway is required — this is purely an option for
  245. environments that already run one.
  246. ## Configuration
  247. | Variable | Required | Default | Description |
  248. |---|:---:|---|---|
  249. | `PFSENSE_URL` | Yes | — | pfSense URL (e.g., `https://192.168.1.1`) |
  250. | `AUTH_METHOD` | | `api_key` | `api_key`, `basic`, or `jwt` |
  251. | `PFSENSE_API_KEY` | * | — | REST API key |
  252. | `PFSENSE_USERNAME` | * | — | pfSense username (for basic/jwt) |
  253. | `PFSENSE_PASSWORD` | * | — | pfSense password (for basic/jwt) |
  254. | `PFSENSE_VERSION` | | `CE_2_8_1` | Current: `CE_2_8_1`, `CE_2_9_0`, `PLUS_25_11_1`, `PLUS_26_03`, `PLUS_26_03_1`, `PLUS_26_07`. Legacy (still accepted): `CE_2_8_0`, `PLUS_24_11`, `PLUS_25_11`, `CE_26_03` |
  255. | `VERIFY_SSL` | | `true` | `false` disables certificate checking entirely — prefer `PFSENSE_CA_FILE` |
  256. | `PFSENSE_CA_FILE` | | — | PEM file for pfSense's private/self-signed CA, so verification stays on |
  257. | `API_TIMEOUT` | | `30` | Request timeout in seconds |
  258. | `MCP_READ_ONLY` | | `false` | Only expose read-only tools |
  259. | `MCP_ENABLE_LOG_FILES` | | `true` | Set `false` to remove `get_log_file` (raw `/var/log/*` reads via command sink) |
  260. Boolean settings accept `true/false`, `1/0`, `yes/no` or `on/off`. Any other value stops the server at startup rather than guessing, so a typo can't turn off TLS verification.
  261. <details>
  262. <summary>All configuration options</summary>
  263. | Variable | Default | Description |
  264. |---|---|---|
  265. | `ENABLE_HATEOAS` | `false` | Enable HATEOAS links in API responses |
  266. | `LOG_LEVEL` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR` |
  267. | `MCP_TRANSPORT` | `stdio` | `stdio` or `streamable-http` |
  268. | `MCP_HOST` | `127.0.0.1` | Bind address for HTTP mode |
  269. | `MCP_PORT` | `3000` | Port for HTTP mode |
  270. | `MCP_BIND_ADDR` | `127.0.0.1` | Docker Compose only: host address the published port binds to |
  271. | `MCP_API_KEY` | — | Bearer token for HTTP transport (required) |
  272. | `MCP_ALLOWED_ORIGINS` | localhost | Comma-separated allowed origins |
  273. | `MCP_AUDIT_LOG` | — | Path to audit log file (JSON lines) |
  274. | `MCP_RATE_LIMIT_DELETE` | `10` | Max deletes per 60 seconds |
  275. | `MCP_RATE_LIMIT_CREATE` | `20` | Max creates per 60 seconds |
  276. | `MCP_RATE_LIMIT_UPDATE` | `30` | Max settings changes (`update_*`, `apply_*`, `enable_*`/`disable_*`) per 60 seconds |
  277. | `MCP_RATE_LIMIT_CRITICAL` | `2` | Max critical ops per 300 seconds |
  278. | `MCP_ALLOWED_TOOLS` | all | Comma-separated allowlist of write tools. Read tools are always available; `get_log_file` is controlled by `MCP_ENABLE_LOG_FILES` |
  279. | `MCP_ROLLBACK_BUFFER` | `50` | Rollback entries kept in memory |
  280. | `RESPONSE_FORMAT` | `json` | `gcf` re-encodes tool results as [Graph Compact Format](https://gcformat.com) for fewer tokens (requires the `gcf` extra) |
  281. </details>
  282. ### Response Encoding (GCF)
  283. By default the tools return JSON. Setting `RESPONSE_FORMAT=gcf` returns each eligible tool result as a single [Graph Compact Format](https://gcformat.com) block instead: the record arrays these read tools produce (firewall rules, aliases, DHCP leases, certificates, DNS records) have their repeated field names factored into one header, cutting the token cost when the result crosses the LLM boundary. Results that are not a single JSON body — or that GCF would not shrink — stay JSON (see below).
  284. Install the optional extra into the server's environment and set the variable:
  285. ```bash
  286. pip install '.[gcf]' # from a clone of this repo
  287. export RESPONSE_FORMAT=gcf
  288. # or, with uvx (the extra must go into uvx's isolated tool environment):
  289. RESPONSE_FORMAT=gcf uvx --with 'gcf-python[fastmcp]==2.7.1' \
  290. --from git+https://github.com/gensecaihq/pfsense-mcp-server pfsense-mcp-server
  291. ```
  292. It is opt-in and conservative — GCF is used only when it is both smaller than the JSON and a verified lossless round-trip, otherwise the JSON is kept, so no record is ever dropped or altered. `structuredContent` is preserved, so output-schema validation and non-model clients keep receiving JSON. If the `gcf` extra is not installed, the server logs a warning and continues with JSON.
  293. Token savings on representative 30-record results (o200k tokens, lossless; reproduce with `python benchmarks/gcf_benchmark.py`):
  294. | Result | JSON | GCF | Savings |
  295. |---|---:|---:|---:|
  296. | Firewall rules | 1,995 | 936 | **53.1%** |
  297. | Aliases | 1,065 | 594 | **44.2%** |
  298. | DHCP leases | 2,314 | 1,606 | **30.6%** |
  299. ## Testing
  300. ```bash
  301. python3 -m pytest tests/ -v # 661 tests
  302. python3 -m pytest tests/ --cov=src # with coverage (~50%)
  303. ```
  304. The suite includes a **wire-contract layer** (`tests/contract/`) that asserts every tool's payload against the real pfSense REST API v2.10.2 schema (distilled from the upstream OpenAPI spec), so a wrong field name or type is a failing test rather than a silent misconfiguration. CI runs on Python 3.11/3.12/3.13 with `pip-audit` dependency scanning.
  305. In addition to the in-process suite, an **end-to-end protocol smoke test** drives
  306. the server over the real MCP wire protocol using the official
  307. [MCP Inspector](https://github.com/modelcontextprotocol/inspector) CLI. It covers
  308. both transports and runs in CI on every push:
  309. ```bash
  310. make test-e2e # or: ./scripts/inspector_smoke.sh (needs node/npx, jq)
  311. ```
  312. It verifies the initialize handshake, the 332-tool listing with annotations,
  313. the guardrail confirm-gate over the wire, read-only mode, and HTTP bearer-auth
  314. plus Origin enforcement — no pfSense instance required.
  315. ## MCP Specification Compliance
  316. Compliant with [MCP 2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25) — the newest revision with stable SDK support — and negotiates down to older revisions per connection, so existing clients keep working:
  317. - `ToolAnnotations` on all 332 tools (readOnlyHint, destructiveHint, idempotentHint)
  318. - `serverInfo.version` and `instructions` provided
  319. - Origin header validation (MUST requirement)
  320. - Bearer token auth with timing-safe comparison
  321. - Default bind to localhost per spec SHOULD
  322. - stdio and Streamable HTTP transports
  323. ### The stateless 2026-07-28 revision
  324. [MCP 2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28/changelog) removes the `initialize` handshake and protocol-level sessions, so every request stands on its own. SDK support ships in fastmcp 4, which is now stable (4.0.5).
  325. **Status:** this release pins fastmcp 3.x (MCP 2025-11-25). A non-blocking CI job runs the full test suite and the MCP Inspector smoke test against fastmcp 4.0.x, and both pass unchanged. The server holds no session state by design, and it uses none of the features that 2026-07-28 deprecates (Roots, Sampling, MCP Logging).
  326. The pin will move to fastmcp 4 once the smoke test also covers sessionless requests, which skip `initialize`. fastmcp 4 negotiates the protocol version per connection, so clients that use the handshake will keep working.
  327. ## Project Structure
  328. ```
  329. src/
  330. main.py Entry point (transports, read-only filter, key validation)
  331. server.py FastMCP instance + API client
  332. client.py pfSense REST API v2 HTTP client (retry/backoff, pooling)
  333. guardrails.py Risk classification, confirm gate, rate limit, audit, redaction
  334. helpers.py Validation, parsing, pagination, safety guards
  335. models.py Data models
  336. middleware.py HTTP bearer auth + Origin validation + /health
  337. tools/ 34 tool modules (332 tools)
  338. scripts/
  339. generate_contract.py Regenerate the wire contract from an OpenAPI spec
  340. generate_token.py Generate a secure MCP_API_KEY bearer token
  341. inspector_smoke.sh End-to-end MCP protocol smoke test (MCP Inspector CLI)
  342. tests/ 661 tests (incl. tests/contract/ wire-contract suite)
  343. ```
  344. See [ARCHITECTURE.md](ARCHITECTURE.md) for the request lifecycle, guardrail
  345. model, and wire-contract layer; [SECURITY.md](SECURITY.md) for disclosure and
  346. hardening; and [RELEASE_AUDIT.md](RELEASE_AUDIT.md) for the audit and roadmap.
  347. ## Known Limitations
  348. These are tracked for the next release:
  349. - About 11 update/delete tools for nested objects don't send the `parent_id` the REST API requires, so those calls fail ([#79](https://github.com/gensecaihq/pfsense-mcp-server/issues/79)). Affected objects are DHCP address pools and custom options, traffic-shaper queues, IPsec encryption entries and schedule time ranges.
  350. - `create_ipsec_phase1` and `create_ipsec_phase2` don't yet send the nested encryption settings the API requires. Fixing them needs validation against a live pfSense.
  351. - The REST API has no config-restore endpoint, so rolling back a change is a manual step in the webGUI. Use the revision ID that guarded tools return.
  352. - Each server process manages a single pfSense instance.
  353. ## Contributing
  354. We need real-world testing across diverse pfSense environments. See [CONTRIBUTING](CONTRIBUTING.md) or:
  355. 1. Fork and create a feature branch
  356. 2. Run `python3 -m pytest tests/ -v`
  357. 3. Submit a PR
  358. **Ideas:** integration tests against real pfSense, additional package support (Snort, Suricata), Ollama local LLM bridge, multi-instance management.
  359. ## License
  360. [MIT](LICENSE)
  361. ## Acknowledgments
  362. - [jaredhendrickson13](https://github.com/jaredhendrickson13) / [pfrest](https://github.com/pfrest) — pfSense REST API v2 package
  363. - [JeremiahChurch](https://github.com/JeremiahChurch) — modular rewrite (PR #5), log endpoint OOM safeguards (PR #6), DHCP static-mapping search fix (PR #91)
  364. - [shawnpetersen](https://github.com/shawnpetersen) — API v2 endpoint discovery (PR #3)
  365. - [aemitic](https://github.com/aemitic) — DELETE-body fix (PR #9), firewall `ipprotocol` for IPv6/dual-stack (PR #10), `logconfigchanges` (PR #11)
  366. - [pbhorjee](https://github.com/pbhorjee) — live-status diagnostics fix (PR #21), firewall-log freshness + exact-IP filtering (PR #23), redirect credential guard (PR #72), 503 write-retry fix (PR #74), transport-error context (PR #75), alias edit locking (PR #76), retry jitter and budget (PR #77), private-CA report (#73)
  367. - [DrewKolstad](https://github.com/DrewKolstad) — interface addressing, null-safe search filters, WireGuard allowed IPs, DHCP lease times (PR #78)
  368. - [msarg44](https://github.com/msarg44) — `get_pf_table` / `get_config_revision` fix (PR #80)
  369. - [cbrown350](https://github.com/cbrown350) — `get_log_file` raw log reads (PR #90)
  370. - [blackwell-systems](https://github.com/blackwell-systems) — optional GCF response encoding (PR #87)
  371. - [bholland-bh](https://github.com/bholland-bh) — pfSense CE 2.9.0 / Plus 26.07 support request (#88)
  372. - [hossamnagy](https://github.com/hossamnagy) — resilient startup on transient preflight failure (PR #14)
  373. - [bill-mccormick-dg](https://github.com/bill-mccormick-dg) — independent DELETE-body fix (PR #16)
  374. - [w1ld3r](https://github.com/w1ld3r) — DELETE and remote-syslog bug reports (#12, #13)
  375. - tvlc — WebGUI port type-mismatch report (#7)
  376. - [renanwilliam](https://github.com/renanwilliam) — uvx/pipx packaging request (#8)
  377. - [Netgate](https://netgate.com) — pfSense
  378. - [FastMCP](https://gofastmcp.com) — MCP framework

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.