mcp-pfsense

MCP server for managing pfSense firewalls through AI assistants like Claude, ChatGPT, and Copilot.

> Requires: pfrest package installed on your pfSense instance (provides the REST API).

Features

19 tools across 7 categories:

Safety

• Two-step confirmation for destructive operations (delete rules, delete mappings, restart services, apply changes): the tool returns a warning on first call and only executes when called again with `confirm=true`.
• Writes are staged, not live. Like the pfSense WebGUI, `add_*` and `delete_*` store the change in the config but do not activate it. The tool response says so (`applied: false`, plus a `pending` note). Activate with `apply_changes(subsystem, confirm=true)` — which reloads that subsystem, including anything a human left staged in the WebGUI — or pass `apply=true` on the write itself when you explicitly want a one-shot change. Nothing the assistant does reaches the packet filter without one of those two explicit steps.
• `delete_dhcp_static_mapping` takes the mapping's `interface` (its `parent_id` in `list_dhcp_static_mappings`) and `mapping_id`; a mapping is addressed by both.

Installation

# Using uvx (recommended)
uvx mcp-pfsense

# Using pip
pip install mcp-pfsense

Prerequisites

1. pfSense with pfrest package installed

2. A user account with API access (typically `admin`)

Configuration

Set environment variables:

Claude Desktop

Add to `claude_desktop_config.json`:

{
  "mcpServers": {
    "pfsense": {
      "command": "uvx",
      "args": ["mcp-pfsense"],
      "env": {
        "PFSENSE_HOST": "10.10.10.1",
        "PFSENSE_PASSWORD": "your-password"
      }
    }
  }
}

Claude Code

claude mcp add pfsense -- uvx mcp-pfsense

Then set environment variables in your shell or `.env` file.

Usage Examples

Once connected, ask your AI assistant:

• *"What's the pfSense system status?"*
• *"Show me all firewall rules on the LAN interface"*
• *"List active DHCP leases"*
• *"Add a DNS entry for nas.home.lan pointing to 10.10.10.50"*
• *"What devices are connected to the network?"* (ARP table)
• *"Show gateway health and latency"*
• *"Create a firewall rule to allow TCP port 8080 on LAN"*
• *"Reserve IP 10.10.10.60 for MAC aa:bb:cc:dd:ee:20"*

API Compatibility

• pfSense: 2.7.x and 2.8.x
• pfrest: REST API v2 — any v2.x release, except `list_dhcp_static_mappings`, which needs v2.7.0 or later (it uses the `/services/dhcp_server/static_mappings` collection endpoint added in that release).
• Python: 3.11+

The endpoint, parameters and encoding each tool uses are pinned by `tests/test_client_endpoints.py` and `tests/test_wire_format.py`, derived from the pfrest v2 endpoint definitions. Versions before 0.2.0 called several endpoints that do not exist in pfrest v2 (see Troubleshooting).

> Note: pfrest runs on nginx (port 80 by default), separate from the pfSense WebGUI (lighttpd on port 443). If your pfrest is configured on a non-standard port, set `PFSENSE_PORT` and `PFSENSE_SCHEME` accordingly.

Troubleshooting

Only `get_system_status` and `get_arp_table` work; everything else returns 400/404

mcp-pfsense 0.1.1 and earlier called singular endpoints for listing (`/interface`, `/firewall/rule`, `/firewall/alias`) and legacy paths that pfrest v2 does not serve (`/status/dhcp_leases`, `/services/dhcpd/static_mapping`, `/services/unbound/host_override`, `/status/gateway`, `/status/service` for GET). Upgrade to 0.2.0 or later.

`403` on `list_services` or other reads

pfrest checks the privileges of the API user per endpoint. Grant the user the `api-v2-*` privileges for the endpoints you need (or `page-all` for full access) under System → User Manager.

`ModuleNotFoundError: No module named 'mcp.server.fastmcp'`

The MCP Python SDK 2.0 removed the module that mcp-pfsense 0.1.1 and earlier import, so fresh installs (`uvx mcp-pfsense`, `pip install`) failed on startup. Upgrade to 0.2.0 or later, which pins `mcp