How do I install MCP Pfsense?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does MCP Pfsense need an API key?

No required environment variable is listed on this record.

What transport does MCP Pfsense use?

MCP Pfsense runs locally over stdio.

When was MCP Pfsense last checked?

Last checked 2026-11-12. Manage pfSense firewalls through AI assistants — rules, DHCP, DNS, and more

MCP Pfsense MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

uvx mcp-pfsense==0.3.1

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1claude mcp add io.github.antonio-mello-ai-mcp-pfsense -- uvx mcp-pfsense==0.3.1

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.antonio-mello-ai-mcp-pfsense": {4      "command": "uvx",5      "args": [6        "mcp-pfsense==0.3.1"7      ]8    }9  }10}

claude_desktop_config.json

Local · pypiPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 0.3.1
License

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

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	`get_system_status`, `get_interfaces`	Version, CPU, memory, uptime, temperature, network interfaces
Firewall	`list_firewall_rules`, `add_firewall_rule`, `delete_firewall_rule`, `list_firewall_aliases`	Rule management with interface filtering, alias listing
DHCP	`list_dhcp_leases`, `list_dhcp_static_mappings`, `add_dhcp_static_mapping`, `delete_dhcp_static_mapping`	Active leases, IP reservations
DNS	`list_dns_host_overrides`, `add_dns_host_override`, `delete_dns_host_override`	Unbound DNS Resolver host overrides
Pending changes	`get_pending_changes`, `apply_changes`	See what is staged per subsystem (firewall, dhcp, dns) and apply it
Monitoring	`get_gateway_status`, `get_arp_table`, `list_services`, `get_firewall_logs`	Gateway health, connected devices, service status, recent raw firewall log entries
Services	`restart_service`	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_* 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

pfSense with pfrest package installed
A user account with API access (typically admin)

Configuration

Set environment variables:

Variable	Required	Default	Description
`PFSENSE_HOST`	Yes	—	pfSense hostname or IP
`PFSENSE_PASSWORD`	Yes	—	API user password
`PFSENSE_USERNAME`	No	`admin`	API username
`PFSENSE_PORT`	No	`443`	API port
`PFSENSE_SCHEME`	No	`https`	`http` or `https`
`PFSENSE_VERIFY_SSL`	No	`false`	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-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/antonio-mello-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

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install MCP Pfsense?

Does MCP Pfsense need an API key?

What transport does MCP Pfsense use?

When was MCP Pfsense last checked?

Documentation

mcp-pfsense

Features

Safety

Installation

Prerequisites

Configuration

Claude Desktop

Claude Code

Usage Examples

API Compatibility

Troubleshooting

Only get_system_status and get_arp_table work; everything else returns 400/404

403 on list_services or other reads

ModuleNotFoundError: No module named 'mcp.server.fastmcp'

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

Development

License

Only `get_system_status` and `get_arp_table` work; everything else returns 400/404

`403` on `list_services` or other reads

`ModuleNotFoundError: No module named 'mcp.server.fastmcp'`