Mcp Pfsense

io.github.antonio-mello-ai由 GitHub 账号 antonio-mello-ai 发布v0.3.1更新于 Nov 4, 2026

Manage pfSense firewalls through AI assistants — rules, DHCP, DNS, and more

概览

AI 生成的概览

让 AI 助手管理 pfSense 防火墙:防火墙规则、DHCP 保留、DNS 覆盖、状态、日志与服务重启。

可以做什么
  • 读取系统状态、网络接口、网关健康、ARP 表、服务状态与最近的防火墙日志
  • 列出防火墙规则与别名,并新增或删除规则
  • 列出 DHCP 租约与静态映射,并新增或删除 IP 保留
  • 列出、新增和删除 Unbound DNS 主机覆盖
  • 查看各子系统的待应用变更,并应用已暂存的防火墙、DHCP 或 DNS 变更
  • 按名称重启 pfSense 服务
适用场景
适合需要管理 pfSense 防火墙、希望助手查看其状态或完成常规规则、DHCP 保留和 DNS 覆盖调整而不必逐项操作 WebGUI 的场景。也可用于只读监控网关健康、在线设备和日志。
运行要求
以本地 Python 包运行(Python 3.11+),可通过 uvx 或 pip 安装。需要已安装 pfrest REST API 包的 pfSense 设备,以及具备 API 权限的用户账号。需配置 PFSENSE_HOST 和 PFSENSE_PASSWORD,可选 PFSENSE_USERNAME、PFSENSE_PORT、PFSENSE_SCHEME、PFSENSE_VERIFY_SSL。需要能访问防火墙的网络。
安装前请注意
该服务器持有防火墙管理员凭据(PFSENSE_PASSWORD),并能改动实际网络策略:新增或删除规则、DHCP 保留和 DNS 覆盖,以及重启服务。写入会先暂存,直到调用 apply_changes 才生效,而该操作也会一并激活他人在 WebGUI 中暂存但尚未审核的变更。破坏性操作需 confirm=true。SSL 校验默认关闭(PFSENSE_VERIFY_SSL)。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Mcp Pfsense,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

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:

CategoryToolsDescription
Systemget_system_status, get_interfacesVersion, CPU, memory, uptime, temperature, network interfaces
Firewalllist_firewall_rules, add_firewall_rule, delete_firewall_rule, list_firewall_aliasesRule management with interface filtering, alias listing
DHCPlist_dhcp_leases, list_dhcp_static_mappings, add_dhcp_static_mapping, delete_dhcp_static_mappingActive leases, IP reservations
DNSlist_dns_host_overrides, add_dns_host_override, delete_dns_host_overrideUnbound DNS Resolver host overrides
Pending changesget_pending_changes, apply_changesSee what is staged per subsystem (firewall, dhcp, dns) and apply it
Monitoringget_gateway_status, get_arp_table, list_services, get_firewall_logsGateway health, connected devices, service status, recent raw firewall log entries
Servicesrestart_serviceRestart 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

bash
# Using uvx (recommended)uvx mcp-pfsense
# Using pippip install mcp-pfsense

Prerequisites

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

Configuration

Set environment variables:

VariableRequiredDefaultDescription
PFSENSE_HOSTYes—pfSense hostname or IP
PFSENSE_PASSWORDYes—API user password
PFSENSE_USERNAMENoadminAPI username
PFSENSE_PORTNo443API port
PFSENSE_SCHEMENohttpshttp or https
PFSENSE_VERIFY_SSLNofalseVerify SSL certificate

Claude Desktop

Add to claude_desktop_config.json:

json
{  "mcpServers": {    "pfsense": {      "command": "uvx",      "args": ["mcp-pfsense"],      "env": {        "PFSENSE_HOST": "10.10.10.1",        "PFSENSE_PASSWORD": "your-password"      }    }  }}

Claude Code

bash
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

bash
git clone https://github.com/felhen-ai/mcp-pfsense.gitcd mcp-pfsensepython -m venv .venvsource .venv/bin/activatepip install -e ".[dev]"
# Run testspytest
# Lint and type checkruff 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.

来源:README.md,提交 91891e0

工具

20

get_system_status

Get pfSense system status including version, CPU, memory, uptime, and temperature.

无需输入参数。

get_interfaces

List all network interfaces with status and configuration.

无需输入参数。

list_firewall_rules

List firewall rules, optionally filtered by interface.

输入参数interface

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.

输入参数type必填applydescrsourcedstportprotocolinterface必填ipprotocoldestination

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.

输入参数applyconfirmrule_id必填

list_firewall_aliases

List firewall aliases (IP groups, port groups, URL lists).

无需输入参数。

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.

输入参数interface

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.

输入参数mac必填applydescripaddr必填hostnameinterface必填

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.

输入参数applyconfirminterface必填mapping_id必填

list_dns_host_overrides

List DNS Resolver host overrides (local DNS entries).

无需输入参数。

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.

输入参数ip必填host必填applydescrdomain必填

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.

输入参数applyconfirmoverride_id必填

get_pending_changes

Check whether a subsystem ('firewall', 'dhcp' or 'dns') has staged, unapplied changes.

输入参数subsystem必填

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.

输入参数confirmsubsystem必填

get_gateway_status

Get gateway status including latency, packet loss, and online state.

无需输入参数。

get_arp_table

Get ARP table showing connected devices (IP, MAC, interface).

无需输入参数。

list_services

List all services and their running status.

无需输入参数。

restart_service

Restart a service by name. Requires confirm=true.

输入参数name必填confirm

get_firewall_logs

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.

输入参数limit

版本历史

2
  1. v0.3.1最新Nov 4, 2026
  2. v0.2.0Sep 16, 2026

评分

已满足适用检查项的 90%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分
  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。

  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分