mcp-pfsense

mcp-pfsense

通过 Claude、ChatGPT 和 Copilot 等 AI 助手管理 pfSense 防火墙的 MCP 服务。

要求：pfrest 软件包必须安装在 pfSense 实例上（提供 REST API）。

功能

涵盖 7 个类别的 20 个工具：

类别	工具	描述
系统	get_system_status、get_interfaces	版本、CPU、内存、运行时间、温度、网络接口
防火墙	list_firewall_rules、add_firewall_rule、delete_firewall_rule、list_firewall_aliases	规则管理（支持按接口筛选）、别名列表
DHCP	list_dhcp_leases、list_dhcp_static_mappings、add_dhcp_static_mapping、delete_dhcp_static_mapping	活动租约、IP 保留
DNS	list_dns_host_overrides、add_dns_host_override、delete_dns_host_override	Unbound DNS Resolver 主机覆盖项
待处理更改	get_pending_changes、apply_changes	查看各子系统（防火墙、dhcp、dns）中暂存的内容并应用更改
监控	get_gateway_status、get_arp_table、list_services、get_firewall_logs	网关运行状况、已连接设备、服务状态、近期原始防火墙日志条目
服务	restart_service	重启任意 pfSense 服务

安全性

• 破坏性操作需两步确认（删除规则、删除映射、重启服务、应用更改）：首次调用时工具会返回警告，只有再次调用并设置 confirm=true 后才会执行。
• 写入操作会暂存，不会立即生效。 与 pfSense WebGUI 一样，add_* 和 delete_* 会将更改保存到配置中，但不会激活更改。工具响应会说明这一点（applied: false，并附带 pending 提示）。使用 apply_changes(subsystem, confirm=true) 激活更改——这会重新加载该子系统，包括人工在 WebGUI 中暂存的任何内容；或者在写入操作本身传入 apply=true，以明确要求一次性应用更改。除非执行这两种明确操作之一，否则助手所做的任何更改都不会影响数据包过滤器。
• delete_dhcp_static_mapping 需要提供映射的 interface（即 list_dhcp_static_mappings 中的 parent_id）和 mapping_id；必须同时提供这两个值才能定位映射。

安装

# Using uvx (recommended)
uvx mcp-pfsense

# Using pip
pip install mcp-pfsense

前置条件

1. 已安装 pfrest 软件包的 pfSense
2. 具有 API 访问权限的用户账户（通常为 admin）

配置

设置环境变量：

变量	必需	默认值	描述
PFSENSE_HOST	是	—	pfSense 主机名或 IP
PFSENSE_PASSWORD	是	—	API 用户密码
PFSENSE_USERNAME	否	admin	API 用户名
PFSENSE_PORT	否	443	API 端口
PFSENSE_SCHEME	否	https	http 或 https
PFSENSE_VERIFY_SSL	否	false	验证 SSL 证书

Claude Desktop

添加到 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

然后在 shell 或 .env 文件中设置环境变量。

使用示例

连接后，可以向 AI 助手提问：

• “pfSense 系统状态如何？”
• “显示 LAN 接口上的所有防火墙规则”
• “列出活动 DHCP 租约”
• “添加一条 DNS 记录，将 nas.home.lan 指向 10.10.10.50”
• “网络上连接了哪些设备？”（ARP 表）
• “显示网关运行状况和延迟”
• “显示最近的 50 条防火墙日志”（只读 get_firewall_logs）
• “创建一条防火墙规则，允许 LAN 上的 TCP 端口 8080”
• “为 MAC aa:bb:cc:dd:ee:20 保留 IP 10.10.10.60”

API 兼容性

• pfSense：2.7.x 和 2.8.x
• pfrest：REST API v2——任何 v2.x 版本，但 list_dhcp_static_mappings 除外，该工具需要 v2.7.0 或更高版本（它使用该版本新增的 /services/dhcp_server/static_mappings 集合端点）。
• Python：3.11+

每个工具使用的端点、参数和编码均由 tests/test_client_endpoints.py 和 tests/test_wire_format.py 固定，这些测试基于 pfrest v2 端点定义。0.2.0 之前的版本调用了若干 pfrest v2 中不存在的端点（见“故障排查”）。

注意：pfrest 运行在 nginx 上（默认端口为 80），与 pfSense WebGUI（运行在端口 443 上的 lighttpd）相互独立。如果 pfrest 配置使用了非标准端口，请相应设置 PFSENSE_PORT 和 PFSENSE_SCHEME。

故障排查

只有 get_system_status 和 get_arp_table 可用；其他所有操作都返回 400/404

mcp-pfsense 0.1.1 及更早版本在列出内容时调用了单数形式的端点（/interface、/firewall/rule、/firewall/alias），还调用了 pfrest v2 不提供的旧路径（GET 请求对应的 /status/dhcp_leases、/services/dhcpd/static_mapping、/services/unbound/host_override、/status/gateway、/status/service）。请升级到 0.2.0 或更高版本。

list_services 或其他读取操作返回 403

pfrest 会针对每个端点检查 API 用户的权限。在 System → User Manager 下为用户授予所需端点对应的 api-v2-* 权限（或授予 page-all 以获得完整访问权限）。

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

MCP Python SDK 2.0 移除了 mcp-pfsense 0.1.1 及更早版本导入的模块，因此全新安装（uvx mcp-pfsense、pip install）会在启动时失败。请升级到 0.2.0 或更高版本，该版本固定使用 mcp<2。如果必须继续使用旧版 mcp-pfsense：uvx --with "mcp<2" mcp-pfsense。

规则／映射／覆盖项已创建，但未生效

这是默认行为：写入操作会暂存（见 安全性）。使用 get_pending_changes(subsystem) 检查，并通过 apply_changes(subsystem, confirm=true) 激活，或在 WebGUI 中操作。如果写入返回 200，但完全没有保存任何内容，则说明 pfrest 的 read_only 设置已开启（System → REST API → Settings）。

开发

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/

许可证

MIT