MCP Pfsense

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

20 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"*
• *"Show the 50 most recent firewall log entries"* (read-only get_firewall_logs)
• *"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<2. If you must stay on an older mcp-pfsense: uvx --with "mcp<2" mcp-pfsense.

A rule / mapping / override was created but is not in effect

That is the default: writes are staged (see Safety). Check with get_pending_changes(subsystem) and activate with apply_changes(subsystem, confirm=true), or in the WebGUI. If a write returns 200 but nothing is stored at all, the pfrest `read_only` setting is on (System → REST API → Settings).

Development

git clone https://github.com/felhen-ai/mcp-pfsense.git

cd mcp-pfsense python -m venv .venv source .venv/bin/activate pip install -e ".[dev]"

Run tests

pytest

Lint and type check

ruff check . mypy src/

License

MIT

Repository and registry compatibility

The canonical repository is https://github.com/felhen-ai/mcp-pfsense. Existing GitHub clone and issue URLs redirect to this repository. Do not recreate a repository at the old address, which would remove those redirects.

The canonical MCP Registry identifier is io.github.felhen-ai/mcp-pfsense. The legacy identifier io.github.antonio-mello-ai/mcp-pfsense remains supported with a separate server.legacy.json manifest. Both identifiers install the same mcp-pfsense package from PyPI, and the package name and CLI command remain unchanged. Keep both ownership markers in this README so future releases can be registered under either identifier.