pfsense-mcp-server

A security-first MCP server for pfSense,
featuring cryptographically authorized, recoverable WRITE operations and
optional hardware-backed anti-rollback protection.

MCP (Model Context Protocol) is the open standard AI assistants use to call
tools. This server implements it for pfSense: point an MCP client (Claude,
Codex, Cursor, and others) at it, and it gets strongly typed, read-only
visibility into one pfSense appliance — system, network, firewall, services,
users, certificates, and diagnostics — without exposing raw shell access, an
unaudited scripting surface, or a way to mutate the appliance by accident.

Current production contract: 42 READ tools. 0 WRITE tools. The one
WRITE capability this project has ever built is not reachable without an
operator explicitly opting in, and every individual mutation still
requires a real, cryptographically authorized, human-driven approval
ceremony — see Security-first by design.

That split is deliberate, not incomplete. See
Why this project exists below.

Quick start

python -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install 'pfsense-mcp-server==0.4.2'
install -m 600 /dev/null /absolute/private/path/pfsense-api.key
# put the API key on the first line of that file, 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 (the exact configuration key varies by
client — see verified client examples), confirm it
shows 42 READ tools and no WRITE tools, then try one of the
example prompts below. Full configuration reference,
troubleshooting, and every environment variable:
docs/CONFIGURATION.md.

pfsense-mcp-server is published on
PyPI with
PEP 740 digital attestations verifiable
back to this repository and the exact release commit — no long-lived upload
token exists. To build from source instead, see
CONTRIBUTING.md.

Example prompts

Ask your MCP client things like:

• "Is my WAN gateway up, and what's the current latency and packet loss?"
• "Show me every active DHCP lease on the LAN."
• "What's the link status of each interface right now?"
• "What firewall rules apply to the WAN interface?"
• "Are all the services I've configured actually running?"
• "Which of my certificates expire in the next 30 days?"
• "Is CARP failover healthy across my HA pair?"
• "What DNS resolver overrides are configured, and do any look wrong?"

Each maps to one typed, capability-gated tool — see the
full tool reference for the complete 42-tool catalog.

Why this project exists

I built this project because I wanted AI assistance for pfSense without
giving an LLM the ability to accidentally disconnect my own network.

A firewall is not just another application. It is the foundation
everything else depends on. Any software capable of changing firewall
rules, routing, interfaces, DNS, VPN configuration, or other
network-critical settings also has the ability to make that network
unreachable — and "the model probably won't make a bad change" is not a
safety mechanism, it's a hope. A mistaken tool invocation, a
misunderstood request, an implementation defect, or a weak authorization
boundary is all it takes. I believe those operations deserve a higher
safety standard than simply exposing WRITE tools to an AI model.

This project deliberately started as READ-only. Not because WRITE is
impossible. Not because WRITE is undesirable. Because I believe WRITE
should be earned through architecture rather than enabled by
implementation.

That's the core idea: adding mutation code does not automatically
create production mutation capability. The current production surface
is READ-only by construction, not by convention — enforced by a static
check over the transport layer, verified on every CI run, not a runtime
setting someone could accidentally flip. The v0.3.0 release already
ships a substantial WRITE-safety framework, and every part of it remains
structurally unreachable from the running server.

What this means today:

Current production:

• ✓ 42 READ tools
• ✓ 0 WRITE tools

Update (2026-08-16): every step below has now been exercised
end-to-end, twice, against a disposable, isolated LAB appliance —
never production or home pfSense — with independently-verified live
evidence (see docs/adr/ADR-026-first-write-capability-adapter.md).
The default production MCP contract above is still 0 WRITE tools: that
remains an explicit operator choice (profile selection), not an
architectural gap.

• explicit capability authorization — proven
• Recovery Contracts — proven
• authenticated confirmation — proven
• sealed execution — proven
• reconciliation — proven (offline, production-bound; no live fault
  ever occurred to exercise it against the real appliance)
• anti-rollback — proven (TPM witness genuinely advanced on both real
  writes, independently verified against the physical hardware)
• disposable-lab validation — proven
• explicit owner activation — required for every individual mutation,
  by design; still not something a default configuration or an AI
  session can trigger on its own

flowchart LR
    subgraph today["Active today"]
        direction LR
        A1[MCP client] -->|stdio| A2[42 capability-gated<br/>READ tools]
        A2 --> A3[GET-only client]
        A3 -->|HTTPS GET| A4[(pfSense)]
    end

    subgraph future["Proven twice against a disposable LAB appliance — requires separate owner authorization for every mutation, never reachable via the default profile"]
        direction LR
        B1[Authorized intent] --> B2[Recovery Contract]
        B2 --> B3[Authenticated<br/>owner confirmation]
        B3 --> B4[Sealed executor]
        B4 --> B5[Semantic verification<br/>/ reconciliation]
        B5 --> B6[Disposable-lab<br/>evidence]
    end

Every box in that second half exists as real, tested code and has now
been exercised against a real disposable LAB appliance — a canonical
Recovery Contract bound to the exact target and intent; a closed state
machine with crash-safe, atomic persistence; Ed25519-authenticated owner
confirmation and reconciliation; a sealed executor that is the only
component ever allowed to send one bounded mutating request and classify
what actually happened, rather than assume success. It has never touched
production or home pfSense, and it is not reachable under the default
profile shipped to every new installation — reaching it requires an
operator to explicitly select PFSENSE_PROFILE=write_protected and then
personally drive a real, owner-approved signing ceremony for each
individual mutation; nothing about it is automatic or AI-triggerable on
its own. See
the Tier 1 architecture and the
public roadmap for the complete picture, and
the security model for what's actually enforced,
not just designed.

Different priorities. Other pfSense MCP projects may prioritize
convenience, automation, or rapid feature development. This project
prioritizes minimizing the chance that an AI-assisted action could
unintentionally disrupt critical network infrastructure. Those are
different engineering priorities, not necessarily right or wrong ones.

I don't mind if an AI answers a question incorrectly. I do mind if an AI
accidentally disconnects my house from the Internet. That single design
principle explains almost every architectural decision in this
repository.

Security

• Credential fields (API keys, passwords, private keys) never appear in a
  public model, MCP schema, log line, or exception message — by
  construction, not filtering.
• Fail-closed configuration and strict TLS by default.
• Explicit capability gates: an MCP tool is reachable only if its capability
  is in the selected profile's accepted set.
• The supported transport is local stdio; the process controlling that
  channel is the trust boundary — see
  the threat model for exactly what that does and
  does not cover.

Every claim above is backed by a specific test class, listed with the tests
that enforce it in SECURITY.md. Report
vulnerabilities privately through SECURITY.md — never in a
public issue.

Security-first by design

pfSense MCP Server is built around a deliberately conservative security
model: READ by default, cryptographically controlled WRITE by explicit
authorization. State-changing operations are protected by a
transaction-oriented security architecture designed for AI-initiated
infrastructure changes — not simply an API credential placed behind an
MCP tool.

The security model assumes that an AI agent requesting a mutation is not,
by itself, sufficient authority to perform it. The goal is not to make
AI-generated infrastructure changes merely possible — it is to make them
constrained, attributable, recoverable, and independently verifiable.

Most MCP servers that expose a WRITE-capable API put an API credential
behind a tool call and stop there: if the model calls the tool, the
change happens. This project was built around a different question —
how do you give an AI agent narrowly controlled mutation capability over
critical network infrastructure without ever granting it unrestricted
administrative authority? The answer implemented below is a multi-party
approval pipeline, not a bigger prompt or a stricter system message.

Protected WRITE architecture

• Zero WRITE capabilities exposed by default — reaching the one accepted
  WRITE tool requires an operator to explicitly select
  PFSENSE_PROFILE=write_protected.
• Least-privilege pfSense credentials, scoped to exactly the REST
  endpoints the WRITE path needs — never a broad/administrative account.
• Explicit capability/security-posture gates, independent of and
  additional to profile selection.
• Deterministic plan and execution-intent binding — the exact target
  state is bound cryptographically before anything is authorized.
• Ed25519-signed authorization, produced off-host by a human operator.
• Short-lived, single-use authorization — consumed exactly once,
  independently of confirmation.
• Fresh-state revalidation before execution, with stale-state and
  concurrent-change refusal.
• A RecoveryContract state machine governing every mutation's full
  lifecycle, durable and auditable.
• Independently signed confirmation, using a separate confirmation
  authority from the authorization signer.
• Deterministic execution with authoritative read-back verification
  after every mutation.
• Fail-closed reconciliation on any ambiguous outcome — never a blind
  retry.
• Integrity-protected audit trail and state, MAC-authenticated
  end-to-end.
• Optional hardware-backed TPM monotonic witness for anti-rollback
  protection.

verified=True does not mean WRITE is enabled by default.
Verification, profile/posture selection, authorization, confirmation,
freshness, target state, and execution are separate, independently
enforced gates — every one of them must hold for a given mutation, every
time.

The protected WRITE path has been exercised end-to-end twice, each
time independently verified, against a real disposable LAB pfSense
appliance — never the owner's production/home pfSense — including
least-privilege execution through a dedicated 4-privilege pfSense
identity (never the administrative account), authoritative read-back,
full RecoveryContract lifecycle, and TPM hardware witness advancement
confirmed against the physical device both times. See
docs/adr/ADR-026-first-write-capability-adapter.md
for the complete evidence chain.

Documentation

A browsable version of the full documentation set below is published at
night4me.github.io/pfsense-mcp-server
(built with make docs-serve for a local preview); see
docs/index.md for the same map.

• MCP tool reference
• Configuration reference
• Client setup examples
• Security model · Threat model
• Architecture diagrams · Architecture decisions
• Tier 1 safety architecture · Public roadmap
• Contributing · Support · Security policy

Status

v0.4.2 is the immutable production baseline, published on PyPI. It
is a documentation/packaging-presentation patch over v0.4.1 — no
functional or security-relevant change, and no new security capability
of any kind. It fixes README links that resolve on GitHub but silently
broke when PyPI rendered the same file as the package's
long_description, corrects a stale "41-tool" reference (the public
contract has been 42 tools since v0.3.1), and publishes several
documentation pages (newer ADRs, v0.3.x/v0.4.x acceptance records) that
existed in the repository but were missing from the deployed
documentation site's navigation — see CHANGELOG.md's [0.4.2] entry
for the complete list. The public MCP contract is unchanged (still 42
READ tools by default); the one WRITE capability this repository has
ever added (set_firewall_alias_description_v1) is verified=True
following independently-verified live evidence (ADR-026), but remains
unreachable under the default profile, requires an operator to
explicitly opt into write_protected, and still requires a real,
owner-driven signing ceremony for every individual mutation — see the
security model's "Recovery and WRITE status"
section for the precise, current description. The Tier 1 safety
framework described above remains implemented, tested, structurally
isolated code.

v0.4.1 itself published to PyPI successfully and remains a valid,
installable historical release. v0.4.0 was tagged and its GitHub
Release published, but its PyPI publication failed outright before any
upload was attempted — a build-tool metadata-version incompatibility
(twine rejecting a Hatchling-emitted Metadata-Version: 2.5), fixed
in v0.4.1 by tightening the hatchling build-system ceiling; see
CHANGELOG.md's [0.4.1] entry for the full root cause. Per this
project's own release policy, v0.4.0's tag/Release are preserved
unmoved as an accurate historical record — v0.4.0 was never
successfully published to PyPI. See
docs/ROADMAP.md for what's next.

Contributing

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

License

Licensed under the MIT License.