MCP Pfsense

What antonio-mello-ai/mcp-pfsense MCP server does

The antonio-mello-ai/mcp-pfsense MCP server connects an MCP-compatible assistant to a pfSense firewall through pfrest REST API v2. It covers operational inspection and configuration tasks across seven areas:

• System status and network interface details
• Firewall rule and alias management
• DHCP lease and static reservation management
• Unbound DNS host overrides
• Pending configuration changes
• Gateway health, ARP entries, and service status
• pfSense service restarts

The package supports pfSense 2.7.x and 2.8.x, Python 3.11 or newer, and pfrest REST API v2. Static DHCP mapping listing requires pfrest 2.7.0 or later.

How it works

The antonio-mello-ai/mcp-pfsense MCP server runs locally as a Python command and sends requests to the pfSense REST API. The pfSense host, port, URL scheme, username, password, and TLS verification behavior come from environment variables.

Configuration writes are intentionally staged by default, matching the pfSense WebGUI workflow. Adding or deleting a rule, DHCP mapping, or DNS override changes the stored configuration but does not activate it. An assistant can inspect pending changes and apply them for a subsystem, or request a one-shot write with apply=true. Applying a subsystem also activates other changes already staged there, including changes made through the WebGUI.

Destructive operations use a confirmation step. Deleting firewall rules or mappings, restarting services, and applying changes first return a warning; the operation runs only when called again with confirm=true.

Setup and configuration

Install the package with uvx:

uvx mcp-pfsense

The pfSense installation must have the pfrest package installed, and the API user must have permissions for the endpoints the assistant will use. Endpoint-specific api-v2-* privileges can be granted in System → User Manager; page-all provides full access. The pfrest service may use a different port and web server from the pfSense WebGUI, so configure the connection accordingly.

Required variables are PFSENSE_HOST and PFSENSE_PASSWORD. PFSENSE_USERNAME defaults to admin, PFSENSE_PORT defaults to 443, PFSENSE_SCHEME defaults to https, and PFSENSE_VERIFY_SSL defaults to false.

For Claude Desktop, configure a server entry using the uvx command and pass the pfSense host and password in its environment. Claude Code can register the same server with claude mcp add pfsense -- uvx mcp-pfsense.

Tools and capabilities

The package provides 19 tools, including:

• Read system version, CPU, memory, uptime, temperature, and interfaces.
• List, add, and delete firewall rules; filter rules by interface; list aliases.
• List active DHCP leases and static mappings; add or delete reservations.
• List, add, and delete DNS Resolver host overrides.
• Inspect pending firewall, DHCP, or DNS changes and apply a subsystem.
• Check gateway status, view the ARP table, and list services.
• Restart a pfSense service with confirmation.

Limitations and notes

The pfrest package is a hard prerequisite; this server does not provide the REST API itself. API permissions can cause individual reads or writes to return 403. Older releases, 0.1.1 and earlier, used endpoints that are incompatible with pfrest v2, so use version 0.2.0 or newer. If writes return successfully but no configuration is stored, check whether pfrest is configured as read-only.

The delete_dhcp_static_mapping operation requires both the mapping interface, represented by parent_id in the listing response, and the mapping ID. Applying changes can activate any other pending changes in the selected subsystem, not only changes made by the assistant.