Skip to main content
Glama
io.github.antonio-mello-ai/mcp-pfsense

io.github.antonio-mello-ai/mcp-pfsense

by felhen-ai

mcp-pfsense

PyPI Python License: MIT

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.

Related MCP server: pfSense MCP Server

Installation

# Using uvx (recommended)
uvx mcp-pfsense

# Using pip
pip install mcp-pfsense

Prerequisites

  1. pfSense with pfrest package installed

  2. 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/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 tools
add_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

    A3.5/5.0

    Scored across 20 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -