add_dhcp_static_mapping
Create a DHCP static mapping (IP reservation) for a MAC address.
Staged until apply_changes('dhcp') is called or apply=true is passed.
LABSCO SUMMARY
Staged changes and a required confirmation, which is the right posture for a firewall.
A bad rule applied instantly can lock you out of the box you are talking to, so the two-step shape matters more here than in most integrations: writes land in the config marked applied: false, and nothing reaches the packet filter until you apply the subsystem or explicitly pass apply=true. Destructive calls go further and refuse the first attempt outright. One thing to know before you use apply_changes: it activates everything staged in that subsystem, including whatever a human left pending in the pfSense web interface and has not reviewed.
What it is
A client for a pfSense box's REST API: 19 tools across system status, firewall rules and aliases, DHCP leases and reservations, DNS resolver overrides, gateway and ARP monitoring, and service control.
What you get
- System and interface state — version, CPU, memory, uptime, temperature, and every interface with its status and configuration (get_system_status, get_interfaces).
- Firewall rules listed and filtered by interface, added as pass, block or reject, deleted by the ID the listing gave you, and the IP, port and URL alias groups read alongside them (list_firewall_rules, add_firewall_rule, delete_firewall_rule, list_firewall_aliases).
- DHCP both ways: the leases handed out right now with IP, MAC, hostname and lease times, and the static reservations created, listed and removed (list_dhcp_leases, list_dhcp_static_mappings, add_dhcp_static_mapping, delete_dhcp_static_mapping).
- Local names in the Unbound resolver listed, added and deleted (list_dns_host_overrides, add_dns_host_override, delete_dns_host_override).
- A staging model rather than instant writes: check what a subsystem has waiting, then activate it deliberately — or pass apply=true on a single write when you want it live at once (get_pending_changes, apply_changes).
- Monitoring and service control: gateway latency, packet loss and online state; the ARP table of connected devices; every service and whether it is running; and a restart for one that is wedged (get_gateway_status, get_arp_table, list_services, restart_service).
Requirements
A pfSense instance running 2.7.x or 2.8.x with the pfrest REST API package installed, and a user account with API access. Python 3.11 or newer — uvx mcp-pfsense is the shortest route. PFSENSE_HOST and PFSENSE_PASSWORD are required; username defaults to admin, port to 443, scheme to https, and SSL verification is off by default. One tool needs a newer API than the rest: listing DHCP static mappings requires pfrest v2.7.0 or later.
Setup effort
One command plus credentials — uvx mcp-pfsense, then supply credentials
USE CASES
01
Answering what is on my network right now
Read the ARP table and the active leases instead of opening the web interface.
02
Adding a firewall rule you want to review first
Create it staged, check what is pending, then activate it deliberately.
03
Giving a device a fixed address
Reserve the IP against its MAC, then apply the DHCP subsystem when you are ready.
04
Pointing a local name at a local box
Add a host override in the resolver rather than editing hosts files on every machine.
05
Checking whether the link is the problem
Read gateway latency, packet loss and online state, then restart the service that is stuck.
06
Auditing what the firewall actually allows
List the rules per interface and read the alias groups they reference.
19 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
add_dns_host_override
Create a DNS host override entry in Unbound DNS Resolver.
Staged until apply_changes('dns') is called or apply=true is passed.
add_firewall_rule
Add a firewall rule. Type is 'pass', 'block', or 'reject'.
The rule is staged (not active) until apply_changes('firewall') is called or apply=true is passed here.
apply_changes
Apply ALL staged changes of a subsystem ('firewall', 'dhcp' or 'dns'). Requires confirm=true.
This reloads the subsystem, activating every pending change — including any a human staged in the pfSense WebGUI and has not reviewed yet.
delete_dhcp_static_mapping
Delete a DHCP static mapping. Requires confirm=true.
interface is the mapping's DHCP server — the parent_id value returned by list_dhcp_static_mappings; mapping_id is its id there. Staged until apply_changes('dhcp') is called or apply=true is passed.
delete_dns_host_override
Delete a DNS host override by ID. Requires confirm=true.
Staged until apply_changes('dns') is called or apply=true is passed.
delete_firewall_rule
Delete a firewall rule by its ID (the id from list_firewall_rules). Requires confirm=true.
Staged until apply_changes('firewall') is called or apply=true is passed.
get_arp_table
Get ARP table showing connected devices (IP, MAC, interface).
get_gateway_status
Get gateway status including latency, packet loss, and online state.
get_interfaces
List all network interfaces with status and configuration.
get_pending_changes
Check whether a subsystem ('firewall', 'dhcp' or 'dns') has staged, unapplied changes.
get_system_status
Get pfSense system status including version, CPU, memory, uptime, and temperature.
list_dhcp_leases
List active DHCP leases showing IP, MAC, hostname, and lease times.
list_dhcp_static_mappings
List DHCP static mappings (IP reservations), optionally filtered by interface.
Each mapping carries parent_id (its DHCP server / interface) — pass that as interface to delete_dhcp_static_mapping.
list_dns_host_overrides
List DNS Resolver host overrides (local DNS entries).
list_firewall_aliases
List firewall aliases (IP groups, port groups, URL lists).
list_firewall_rules
List firewall rules, optionally filtered by interface.
list_services
List all services and their running status.
restart_service
Restart a service by name. Requires confirm=true.
BEFORE YOU INSTALL
What to know first
Tools you get
19 tools when we connected. Writes are staged until apply_changes runs with confirm true, and destructive tools warn first, running only when called again with confirm true. pfrest's read_only option makes writes report success but store nothing.
Requires
- uvx on PATH
- Python 3.11+
- A pfSense 2.7.x/2.8.x box with the pfrest REST API package installed
- PFSENSE_HOST in your environment
- PFSENSE_PASSWORD in your environment
Where it runs
Both documented clients run the server on your machine.
CONTEXT COST
Light Standing cost
Rated by the size of the 19 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
uvx mcp-pfsenseMCP Clients
Claude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"pfsense": {
"command": "uvx",
"args": [
"mcp-pfsense"
],
"env": {
"PFSENSE_HOST": "10.10.10.1",
"PFSENSE_PASSWORD": "<YOUR_PFSENSE_PASSWORD>"
}
}
}
}Claude Code
CLAUDE CODE · TERMINAL
claude mcp add pfsense -- uvx mcp-pfsenseThen set PFSENSE_HOST and PFSENSE_PASSWORD (required) in your shell or .env file.
