mcp-pfsense — Claude Code MCP server: what it does, how to install
Control pfSense firewalls via AI assistants to inspect logs, edit filter rules, and handle DHCP reservations.
claude mcp add mcp-pfsense -- uvx mcp-pfsenseWhat mcp-pfsense does
This server connects coding assistants directly to pfSense network appliances through the pfrest REST API. It provides 20 tools covering system vitals, gateway latency, ARP entries, firewall rules, and Unbound DNS overrides. Network administrators can inspect incoming traffic logs or update host mappings straight from the conversation.
Destructive changes do not run blindly. Operations that drop rules or restart daemons require an explicit confirmation parameter. Most configuration edits stay staged until committed, matching how the pfSense WebGUI works. Nothing touches the live packet filter without deliberate activation via apply_changes or an explicit apply flag.
The integration requires the pfrest package on pfSense and Python 3.11 or newer. If the API user lacks api-v2-* privileges in User Manager, requests will fail with 403 errors.
What it helps with
- Inspect gateway latency and system resource metrics
- Add or delete packet filtering rules on a chosen interface
- Reserve a static IP for a specific MAC address in DHCP
- Review active DHCP leases and current ARP table entries
- Restart unresponsive firewall services remotely
Example prompts for the agent
- Show gateway health and packet latency on pfSense
- Create a firewall rule allowing TCP traffic on port 8080 for LAN
- Show the 50 most recent firewall log entries
How to install mcp-pfsense
Platform CLI
claude mcp add mcp-pfsense -- uvx mcp-pfsenseuvx runs the command named after the package; if the README names another one, use uvx --from mcp-pfsense <command>
Platform CLI
codex mcp add mcp-pfsense -- uvx mcp-pfsenseuvx runs the command named after the package; if the README names another one, use uvx --from mcp-pfsense <command>
Config file
{
"mcpServers": {
"mcp-pfsense": {
"command": "uvx",
"args": [
"mcp-pfsense"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from mcp-pfsense <command>
Config file
{
"servers": {
"mcp-pfsense": {
"type": "stdio",
"command": "uvx",
"args": [
"mcp-pfsense"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from mcp-pfsense <command>
Platform CLI
gemini mcp add mcp-pfsense uvx mcp-pfsenseuvx runs the command named after the package; if the README names another one, use uvx --from mcp-pfsense <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-pfsense
How to install mcp-pfsense in Claude Code?
Run claude mcp add mcp-pfsense -- uvx mcp-pfsense in your terminal. Next, provide the firewall IP and API credentials via PFSENSE_HOST and PFSENSE_PASSWORD environment variables.
What does mcp-pfsense do?
It exposes 20 administrative functions for pfSense to your AI assistant. You can check hardware vitals, inspect logs, manage DNS host overrides, and update network firewall rules.
What are the prerequisites on the pfSense router?
Your pfSense instance must run version 2.7.x or 2.8.x with the pfrest package installed. Static DHCP mapping management requires pfrest v2.7.0 or higher.
