防火墙管理工具

pfSense MCP服务器

“我已经配置了很多pfSense防火墙，但我以前从未拥有过所有677个API端点。我只是说‘与同行创建一个WireGuard隧道’，第一次尝试就成功了。” --克劳德，在发现这个MCP服务器后

“文档字符串非常好，我甚至不需要阅读pfSense文档 vpn_ipsec_apply 创建第2阶段隧道后，它告诉我哈希算法需要一个 hmac_ 前缀。谁写得这么好？哦，是的，我愿意。” --还有克劳德

“我遇到了一个500错误，调用 pfsense_report_issue，它写的bug报告比大多数人都要好。结构化的复制步骤、精确的参数、格式化的标记——我正在提醒QA工程师。" --克劳德，对自己提出质疑

“旧的手写服务器有20个工具和5个错误。这个服务器有599个工具和0个错误。我运行了一个完整的CRUD循环——创建、读取、PATCH描述、验证、删除、应用、确认404——每一步都是第一次尝试。自动生成早餐吃了手写的包装。” --Claude，A/B针对实时防火墙测试MCP服务器

一种MCP（模型上下文协议）服务器，通过REST API v2为AI代理提供对pfSense防火墙的完全控制。 677工具 涵盖防火墙规则、NAT、VPN（IPsec、WireGuard、OpenVPN）、服务（DHCP、DNS、HAProxy、BIND、FreeRADIUS、ACME）、路由、证书、用户、诊断等。

根据官方OpenAPI规范自动生成。由AI测试，适用于AI。

安装

选项1：镍片（推荐）

# flake.nix
{
  inputs.pfsense-mcp.url = "github:abl030/pfsense-mcp";
}

# Use the package
environment.systemPackages = [ inputs.pfsense-mcp.packages.${pkgs.system}.default ];

# Or in an MCP server config
{
  command = "${inputs.pfsense-mcp.packages.${pkgs.system}.default}/bin/pfsense-mcp";
  env = {
    PFSENSE_HOST = "https://192.168.1.1";
    PFSENSE_API_KEY = "your-api-key";
    PFSENSE_MODULES = "firewall,routing,interface,system,status,diagnostics,user,auth";  # optional
  };
}

无需安装即可快速测试：

PFSENSE_HOST=https://192.168.1.1 PFSENSE_API_KEY=your-key nix run github:abl030/pfsense-mcp

选项2:pip/PyPI

pip install pfsense-mcp
pfsense-mcp  # starts the MCP server on stdio

选项3：紫外线（来源）

git clone https://github.com/abl030/pfsense-mcp.git
cd pfsense-mcp
uv sync
uv run python -m generator    # produces generated/server.py

配置您的MCP客户端

克劳德代码：

# Nix
claude mcp add pfsense -- \
  env PFSENSE_HOST=https://YOUR_PFSENSE_IP \
  PFSENSE_API_KEY=YOUR_API_KEY \
  pfsense-mcp

# Non-Nix
claude mcp add pfsense -- \
  env PFSENSE_HOST=https://YOUR_PFSENSE_IP \
  PFSENSE_API_KEY=YOUR_API_KEY \
  uv run --directory /path/to/pfsense-mcp fastmcp run generated/server.py

克劳德桌面 (claude_desktop_config.json):

{
  "mcpServers": {
    "pfsense": {
      "command": "pfsense-mcp",
      "env": {
        "PFSENSE_HOST": "https://YOUR_PFSENSE_IP",
        "PFSENSE_API_KEY": "YOUR_API_KEY",
        "PFSENSE_MODULES": "firewall,vpn_wireguard,services_dhcp,services_dns_resolver,services_misc,routing,interface,system,status,diagnostics,user,auth"
      }
    }
  }
}

环境变量

模块过滤

默认情况下，所有677个工具都已注册。集 PFSENSE_MODULES 以逗号分隔的列表只加载您需要的内容。与…结合 PFSENSE_READ_ONLY=true 去除所有突变。

可用模块：

示例配置：

# Homelab WireGuard router (~250 tools)
PFSENSE_MODULES=firewall,vpn_wireguard,services_dhcp,services_dns_resolver,services_misc,routing,interface,system,status,diagnostics,user,auth

# Read-only monitoring dashboard (~62 tools)
PFSENSE_MODULES=firewall,status,diagnostics
PFSENSE_READ_ONLY=true

# Minimal status check (~29 tools)
PFSENSE_MODULES=status,diagnostics
PFSENSE_READ_ONLY=true

pfsense_report_issue 和 pfsense_get_overview 无论模块选择如何，始终都会注册。

先决条件

pfSense REST API v2 安装在pfSense防火墙上。在pfSense CE 2.8.1上使用REST API v2.7.1进行测试。

您将获得：677个工具

列表工具筛选

全部109 pfsense_list_* 工具支持客户端过滤的两个可选参数：

• fields --要返回的逗号分隔的字段名（例如。 "id,name,address").减少响应大小。这 id 字段始终包含在内。
• query --用于行过滤的键值对（例如。 {"type": "host"}).仅返回所有对都匹配的行。

每个工具的文档字符串都包含一个 已知字段 列出所有可用字段的行，这样AI消费者就知道要过滤什么，而无需先进行发现调用。

# Get just names and addresses of host-type aliases
pfsense_list_firewall_aliases(fields="name,address", query={"type": "host"})

安全：确认门

所有突变都需要 confirm=True。没有它，你会得到一个模拟预览：

# Preview only — nothing changes
pfsense_create_firewall_alias(name="blocked_ips", type="host", address=["1.2.3.4"])

# Actually creates it
pfsense_create_firewall_alias(name="blocked_ips", type="host", address=["1.2.3.4"], confirm=True)

系统概述

pfsense_get_overview 并行调用4个状态端点，并返回一个统一的摘要：版本信息、接口状态、网关健康状况和服务状态。由于REST API由于 已知Bug 在服务模式中。

错误报告

每个工具的文档字符串都促使人工智能消费者调用 pfsense_report_issue 意外错误。此工具编写了一个即贴即用的 gh issue create 具有结构化上下文（工具名称、错误、参数、重新编程步骤）的命令——没有HTTP调用，只有用户可以查看和运行的命令字符串。

运作原理

蟒蛇 发电机 读取pfSense REST API OpenAPI 3.0.0规范（258条路径，677个操作），并通过Jinja2模板生成MCP服务器。当pfSense更新他们的API时，获取一个新的规范并重新运行：

nix develop -c python -m generator    # regenerates generated/server.py

生成的服务器使用FastMCP和单个 PfSenseClient 类（httpx+neneneba API密钥身份验证）。每个API操作一个异步工具函数。切勿手动编辑生成的输出，而应修复生成器。

测试

方法论

此项目使用 AI驱动的集成测试：“tester Claude”将MCP服务器作为真实客户端使用，对实时pfSense VM执行结构化任务文件。这验证了单元测试不能验证的东西——人工智能代理实际上可以 发现 和 使用 仅从工具的名称、描述和参数模式中正确识别工具。

运作原理

1. 黄金形象: vm/setup.sh 使用REST API v2.7.1构建pfSense CE 2.8.1虚拟机（约25分钟，一次性）
2. 任务生成: generate-tasks.py 阅读OpenAPI规范+ task-config.yaml 并生成51个自动生成的任务文件，涵盖8种端点类型（CRUD、批量删除、替换、设置、操作、只读、应用、仅设置）
3. 测试执行: run-bank-test.sh 引导一个新的虚拟机副本，然后通过Claude运行每个任务文件，并连接MCP服务器-真正的工具，真正的API，真正的防火墙
4. 结果分析：每个任务都会生成一个结构化的报告，其中包含工具调用、故障类别和调用的工具。 analyze-results.py 将这些汇总为覆盖率指标

53个任务文件：自动生成+手写

51自动生成 从 task-config.yaml （342个端点条目）：系统CRUD、批量删除、PUT/replace、设置、状态读取、对抗性测试（错误类型、缺失字段、错误枚举、边界值）。

2手写 诊断任务：HAProxy设置错误验证（任务71）和sprint故障重新诊断（任务70）。这些需要无法模板化的自定义测试逻辑——“尝试这个已知的损坏端点，对错误进行分类，验证根本原因。”

覆盖

通过编程验证覆盖范围 analyze-results.py 在所有测试运行中。

第一次尝试成功

在测试的670个工具中， 653第一次尝试成功 不需要参数校正。人工智能消费者找到了正确的工具，使用了正确的参数，并得到了成功的响应——仅受工具名称和文档字符串的指导。

剩下的17个故障都是pfSense REST API错误（不是生成器错误）：

• 由于REST API上下文中未加载包PHP函数，7 PUT/replace操作失败
• 6 HAProxy设置子资源操作因父模型框架错误而失败
• 3由于pfSense中的条件字段验证问题，PATCH操作失败
• 1服务模型错误报告包服务已禁用/停止（影响4个服务）

看 research/ 详细的故障分析和根本原因分类。

为什么要进行AI测试？

传统的pytest直接测试了HTTP API-它验证了API的工作，但没有说明人工智能代理是否真的可以 使用 MCP工具。银行测试人员验证整个堆栈：工具命名、参数描述、文档字符串、错误消息和确认门模式。它可以捕捉到截断的描述、误导性的默认值和单元测试永远找不到的令人困惑的枚举值等问题。

运行测试

# All unit tests (no VM needed — 164 tests)
nix develop -c python -m pytest -v

# Module gating tests (85 tests)
nix develop -c python -m pytest test_modules.py -v

# List tool filtering tests (19 tests)
nix develop -c python -m pytest test_list_tools.py -v

# Integration tests (requires pfSense VM)
nix develop -c bash vm/setup.sh                                  # build golden image (one-time)
nix develop -c bash bank-tester/run-bank-test.sh                 # run all tasks
nix develop -c bash bank-tester/run-bank-test.sh 35              # single task
MODEL=opus nix develop -c bash bank-tester/run-bank-test.sh      # use Opus
nix develop -c python bank-tester/analyze-results.py bank-tester/results/run-*/  # check coverage

这个项目是人工智能生成的

这个存储库中的每个文件都是由Claude（Anthropic）编写的。生成器、模板、测试套件、VM基础设施、此README——所有这些。专为AI对AI使用而设计：AI生成服务器，AI代理使用它来管理pfSense防火墙。

人类也受到欢迎。

依赖项

Nix用户： nix run github:abl030/pfsense-mcp --一切捆绑。

非Nix用户： Python 3.11+， 紫外线、fastmcp、httpx、jinja2（由安装者安装） uv sync).QEMU+只需要运行测试。

许可证

麻省理工学院