pfSense MCP Server

pfSense MCP服务器

使用自然语言管理pfSense防火墙。327工具。9层安全。一个启动命令。

You: "Block all traffic from 203.0.113.5 on WAN"
Claude: Creates block rule → applies changes → confirms with rollback instructions

为什么存在

管理pfSense防火墙意味着点击web UI选项卡，记住字段名称，并希望您不要错过一条将您拒之门外的规则。有了这个MCP服务器，你可以用简明的英语描述你想要什么，AI处理REST API调用，验证输入，并在任何破坏性的事情发生之前警告你。

是什么让它与众不同：

• 每一次破坏性操作都需要明确的确认，并向您准确显示会发生什么
• 每次删除/重新启动之前自动进行配置备份——使用一行回滚命令
• 速率限制可防止失控的AI循环用规则淹没防火墙
• 输入净化会阻止每个参数中的命令注入、路径遍历和XSS

快速开始

先决条件： Python 3.10+，pfSense REST API v2软件包 安装

git clone https://github.com/gensecaihq/pfsense-mcp-server.git
cd pfsense-mcp-server
pip install -r requirements.txt
cp .env.example .env
# Edit .env: set PFSENSE_URL, AUTH_METHOD, and credentials

连接到克劳德桌面 --添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pfsense": {
      "command": "python3",
      "args": ["-m", "src.main"],
      "cwd": "/path/to/pfsense-mcp-server",
      "env": {
        "PFSENSE_URL": "https://192.168.1.1",
        "AUTH_METHOD": "basic",
        "PFSENSE_USERNAME": "admin",
        "PFSENSE_PASSWORD": "your-password",
        "PFSENSE_VERSION": "CE_2_8_0",
        "VERIFY_SSL": "false"
      }
    }
  }
}

开始与防火墙对话。 打开克劳德桌面并询问：

• *“显示过去一小时内所有堵塞的交通”*
• *“正在运行哪些服务？”*
• *“为端口443创建一个端口转发到192.168.1.50”*
• *“运行完整的系统健康检查”*

你能做什么

每个主要pfSense子系统都有327个工具：

安全第一

人工智能管理生产防火墙需要护栏。此服务器有9层：

"Delete firewall rule 5"

  1. CLASSIFY    → HIGH risk (destructive)
  2. ALLOWLIST   → tool is permitted
  3. SANITIZE    → parameters clean (no injection)
  4. RATE LIMIT  → under 10 deletes/minute
  5. DRY RUN?    → user can preview first
  6. CONFIRM     → blocked until confirm=True
  7. BACKUP      → config revision captured
  8. EXECUTE     → API call made
  9. AUDIT LOG   → action recorded with redacted params

Response includes:
  "config_backup": {
    "pre_change_revision_id": 42,
    "rollback_instruction": "restore_config_backup(revision_id=42, confirm=True)"
  }

每 破坏性操作（52个删除/重新启动/停止工具）需要 confirm=True. 每 创建和更新操作（112个工具）受到速率限制和净化。 每 敏感参数（密码、密钥、令牌）在日志和输出中被编辑。

您还可以：

• 通过 dry_run=True 预览任何破坏性操作而不执行
• 通过 verify_descr="Allow HTTPS" 验证您是否删除了正确的规则（防止ID转换）
• 集 MCP_READ_ONLY=true 仅公开118个只读工具（搜索、获取、诊断）
• 集 MCP_ALLOWED_TOOLS=search_firewall_rules,get_firewall_log 仅限于特定工具

支持的pfSense版本

认证

支持三种方法（在中配置 .env):

部署选项

标准 （默认）--对于克劳德桌面和克劳德代码：

python3 -m src.main

超文本传输协议 --对于远程访问和多客户端设置：

python3 -m src.main -t streamable-http --port 3000

码头工人 --具有只读文件系统的强化容器：

docker compose up

容器安全：非root用户(mcp:1000)只读文件系统，所有功能均已删除， noexec tmpfs， no-new-privileges.

配置

All configuration options

测试

python3 -m pytest tests/ -v          # 308 tests
python3 -m pytest tests/ --cov=src   # with coverage

MCP规范合规性

符合 MCP 2025-11-25 （最新）：

• ToolAnnotations 在所有327个工具上（readOnlyHint、destructiveHint、幂等Hint）
• serverInfo.version 和 instructions 提供
• 源标头验证（必须要求）
• 带有定时安全比较的承载令牌认证
• 根据规范，应默认绑定到localhost
• stdio和流式HTTP传输

项目结构

src/
  main.py              Entry point
  server.py            FastMCP instance + API client
  client.py            pfSense REST API v2 HTTP client
  guardrails.py        9-layer defense-in-depth system
  helpers.py           Validation, parsing, safety guards
  models.py            Data models
  middleware.py        HTTP auth + Origin validation
  tools/               34 tool modules (327 tools)
tests/                 308 tests

贡献

我们需要在不同的pfSense环境中进行真实世界的测试。看 贡献 或者：

1. 分叉并创建特征分支
2. 跑 python3 -m pytest tests/ -v
3. 提交PR

思想： 针对真实pfSense的集成测试、额外的包支持（Snort、Suricata）、Ollama本地LLM桥、多实例管理。

许可证

麻省理工学院

致谢

• 赫雷米亚·丘奇 --模块化重写（PR#5）
• 肖恩·彼得森 -API v2端点发现（PR#3）
• Netgate --pfSense
• FastMCP --MCP框架