io.github.antonio-mello-ai/mcp-pfsense
This MCP server lets an AI assistant inspect and manage a pfSense firewall via pfrest, with staged writes and confirmations for destructive actions.
Get system status and list network interfaces.
List, add, and delete firewall rules; list firewall aliases.
List active DHCP leases and static mappings; add/delete IP reservations.
List, add, and delete Unbound DNS host overrides.
Check staged pending changes and apply changes per subsystem (
firewall,dhcp,dns).Monitor gateway health, ARP table, services, and recent firewall logs.
Restart services by name.
Destructive operations require
confirm=true; writes are staged until explicitly applied.
Provides tools for managing pfSense firewalls through its REST API, including system status, firewall rules, DHCP leases, DNS host overrides, gateway monitoring, ARP table, services, and more.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@io.github.antonio-mello-ai/mcp-pfsense Show me the system status of the pfSense firewall"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
Category | Tools | Description |
System |
| Version, CPU, memory, uptime, temperature, network interfaces |
Firewall |
| Rule management with interface filtering, alias listing |
DHCP |
| Active leases, IP reservations |
DNS |
| Unbound DNS Resolver host overrides |
Pending changes |
| See what is staged per subsystem (firewall, dhcp, dns) and apply it |
Monitoring |
| Gateway health, connected devices, service status, recent raw firewall log entries |
Services |
| Restart any pfSense service |
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_*anddelete_*store the change in the config but do not activate it. The tool response says so (applied: false, plus apendingnote). Activate withapply_changes(subsystem, confirm=true)— which reloads that subsystem, including anything a human left staged in the WebGUI — or passapply=trueon 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_mappingtakes the mapping'sinterface(itsparent_idinlist_dhcp_static_mappings) andmapping_id; a mapping is addressed by both.
Related MCP server: pfSense MCP Server
Installation
# Using uvx (recommended)
uvx mcp-pfsense
# Using pip
pip install mcp-pfsensePrerequisites
pfSense with pfrest package installed
A user account with API access (typically
admin)
Configuration
Set environment variables:
Variable | Required | Default | Description |
| Yes | — | pfSense hostname or IP |
| Yes | — | API user password |
| No |
| API username |
| No |
| API port |
| No |
|
|
| No |
| Verify SSL certificate |
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-pfsenseThen 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_mappingscollection 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_PORTandPFSENSE_SCHEMEaccordingly.
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.
Available Tools
20 toolsadd_dhcp_static_mappingA
Create a DHCP static mapping (IP reservation) for a MAC address.
Staged until apply_changes('dhcp') is called or apply=true is passed.
Inputs: mac (required), ipaddr (required), interface (required), apply, +2 more. Returns: object
add_dns_host_overrideA
Create a DNS host override entry in Unbound DNS Resolver.
Staged until apply_changes('dns') is called or apply=true is passed.
Inputs: ip (required), host (required), domain (required), apply, +1 more. Returns: object
add_firewall_ruleA
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.
Inputs: type (required), interface (required), apply, descr, +5 more. Returns: object
apply_changesA
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.
Inputs: subsystem (required), confirm. Returns: object
delete_dhcp_static_mappingA
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.
Inputs: interface (required), mapping_id (required), apply, confirm. Returns: object
delete_dns_host_overrideA
Delete a DNS host override by ID. Requires confirm=true.
Staged until apply_changes('dns') is called or apply=true is passed.
Inputs: override_id (required), apply, confirm. Returns: object
delete_firewall_ruleA
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.
Inputs: rule_id (required), apply, confirm. Returns: object
get_arp_tableA
Get ARP table showing connected devices (IP, MAC, interface).
Inputs: no named parameters. Returns: result
get_firewall_logsA
Read-only view of recent firewall log entries.
Each entry contains its ID and raw log text from pfrest. limit caps the
number of entries (default 50). This tool only reads logs; it never writes
to the firewall.
Inputs: limit. Returns: result
get_gateway_statusA
Get gateway status including latency, packet loss, and online state.
Inputs: no named parameters. Returns: result
get_interfacesA
List all network interfaces with status and configuration.
Inputs: no named parameters. Returns: result
get_pending_changesA
Check whether a subsystem ('firewall', 'dhcp' or 'dns') has staged, unapplied changes.
Inputs: subsystem (required). Returns: object
get_system_statusA
Get pfSense system status including version, CPU, memory, uptime, and temperature.
Inputs: no named parameters. Returns: object
list_dhcp_leasesA
List active DHCP leases showing IP, MAC, hostname, and lease times.
Inputs: no named parameters. Returns: result
list_dhcp_static_mappingsA
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.
Inputs: interface. Returns: result
list_dns_host_overridesA
List DNS Resolver host overrides (local DNS entries).
Inputs: no named parameters. Returns: result
list_firewall_aliasesA
List firewall aliases (IP groups, port groups, URL lists).
Inputs: no named parameters. Returns: result
list_firewall_rulesC
List firewall rules, optionally filtered by interface.
Inputs: interface. Returns: result
list_servicesA
List all services and their running status.
Inputs: no named parameters. Returns: result
restart_serviceB
Restart a service by name. Requires confirm=true.
Inputs: name (required), confirm. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Most tools target a distinct resource and action, such as firewall rules, DHCP mappings, DNS overrides, logs, and ARP. A few read-only tools like get_arp_table and list_dhcp_leases could be confused when looking for connected devices, but their descriptions clarify the difference.
The set largely uses snake_case verb_noun naming, but read operations are split inconsistently between get_ and list_ (e.g., get_interfaces vs list_firewall_rules). Add/delete pairs are consistent, while apply_changes and get_pending_changes follow a different style.
20 tools is on the heavier side, but it is justified by pfSense's broad scope covering firewall, DHCP, DNS, system status, services, and networking. The count is slightly over the ideal range but not bloated for the domain.
Firewall rules, DHCP static mappings, and DNS overrides each support add/list/delete, and the staged-apply workflow is covered. However, there are no update/edit tools for any managed resource, which is a notable gap for a management server.
Maintenance
Related MCP Connectors
IP intelligence, network diagnostics, and AI service availability tools for AI agents.
34 security tools for AI agents: phishing links, exposure maps, DNS, SSL, PQC, history, pivots.
29 DNS, SEO, SSL, security, WHOIS & mail tools for AI agents. Pay per call (x402) or card API key.
AI-callable tools for API mocking, testing, monitoring, security, and automation.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to manage and configure pfSense routers through the pfSense REST API, offering 240 tools across 17 modules with safety features like confirm gates, config backups, and read-only mode.-
- FlicenseNot gradedqualityAmaintenanceEnables users to manage a pfSense firewall — rules, NAT, VPNs, DNS, DHCP, routing, certificates, services, and diagnostics — in natural language from Claude Desktop, Claude Code, or any MCP client. Wraps 332 wire-format-verified tools for the pfSense REST API with multi-layer safety guardrails, rate limits, explicit confirmation for destructive actions, and config-revision rollback.-
- FlicenseNot gradedqualityAmaintenanceEnables natural-language control of pfSense firewalls from Claude Desktop, Claude Code, or any MCP client, covering firewall rules, NAT, VPN, DNS, DHCP, routing, certificates, users, and diagnostics through 332 wire-format-verified REST API tools. Destructive changes are gated behind explicit confirmation, rate limits, config-revision backups, and audit logging so an AI can safely diagnose and reconfigure a production firewall.-
- FlicenseNot gradedqualityAmaintenanceEnables users to manage and diagnose a pfSense firewall in plain English from Claude Desktop, Claude Code, or any MCP client, covering firewall rules, NAT, VPNs, routing, DNS, DHCP, certificates, services, logs, and troubleshooting through the pfSense REST API. Every configuration change runs through safety guardrails with explicit confirmation, rate limiting, and captured config revisions that can be rolled back.-