STARWARCLOUD STARWAR.AI
返回市场
pfSense-MCP服务器

pfSense-MCP服务器

作者：gensecaihq23 星标更新：2025-08-20
安装使用来源：spider==github.com

项目介绍

pfSense 增强型 MCP 服务器

🚀 下一代模型上下文协议（MCP）服务器，通过 Claude Desktop 和其他 GenAI 应用程序实现与 pfSense 防火墙的自然语言交互。现在具有 pfrest.org 提供的高级 API 功能，包括智能过滤、HATEOAS 导航和企业级控制。

🧪 需要社区测试

⚠️ 重要提示： 此项目需要社区测试和验证！
👥 我们需要您的帮助来使用实际的 pfSense 设备和环境进行测试。

  • 🔍 测试它 使用您的 pfSense 设置
  • 🐛 报告问题 通过 GitHub Issues
  • 🔧 修复错误 并提交 PR
  • 📝 改进文档 根据实际使用情况
  • 💡 贡献功能 和改进

您的测试和贡献将帮助使此项目适用于所有人！

版本 许可证 MCP pfSense API 社区

✨ 增强功能

🎯 核心能力

  • 🗣️ 自然语言接口：使用普通英语通过 Claude 控制 pfSense
  • 🔧 高级 API 集成：完全支持 jaredhendrickson13/pfsense-api v2
  • 🔍 智能过滤：8 种过滤类型（精确匹配、包含、正则表达式、范围），支持多字段
  • 📊 智能分页：高效处理大数据集，支持排序
  • 🔗 HATEOAS 导航：动态 API 探索，带有超媒体控件
  • ⚙️ 控制参数：细粒度操作控制（应用、异步、放置）
  • 🆔 对象ID管理：处理动态ID，基于字段查找

🏢 企业就绪

  • 🔒 多种认证支持：API密钥、基本认证、JWT，遵循安全最佳实践
  • 📈 生产监控：健康检查、指标、审计日志
  • 🐳 容器就绪：Docker部署，加强安全性
  • 🎨 25+ MCP工具：全面的pfSense管理能力
  • ⚡ 高性能：异步操作、缓存、连接池

🎮 支持的pfSense版本

版本状态API包功能
pfSense CE 2.8.0✅ 全面支持下载所有增强功能
pfSense Plus 24.11✅ 全面支持下载所有增强功能

🚀 快速开始

1. 安装pfSense REST API包

在您的pfSense系统上（通过SSH或控制台）：

# 对于pfSense CE 2.8.0
pkg-static add https://github.com/jaredhendrickson13/pfsense-api/releases/latest/download/pfSense-2.8.0-pkg-RESTAPI.pkg

# 对于pfSense Plus 24.11
pkg-static -C /dev/null add https://github.com/jaredhendrickson13/pfsense-api/releases/latest/download/pfSense-24.11-pkg-RESTAPI.pkg

2. 配置pfSense API

  1. 在pfSense webConfigurator中导航到 系统 → REST API
  2. 启用REST API
  3. 生成API密钥：系统 → 用户管理器 → [您的用户] → API密钥
  4. 为您的API用户分配适当的权限

3. 设置MCP服务器

# 克隆仓库
git clone https://github.com/gensecaihq/pfsense-mcp-server.git
cd pfsense-mcp-server

# 安装依赖项
pip install -r requirements.txt

# 配置环境
cp .env.example .env
nano .env  # 添加您的pfSense详细信息

最小.env配置：

PFSENSE_URL=https://your-pfsense.local
PFSENSE_API_KEY=your-api-key-here
PFSENSE_VERSION=CE_2_8_0  # 或 PLUS_24_11
AUTH_METHOD=api_key
VERIFY_SSL=true
ENABLE_HATEOAS=false  # 设置为true以启用导航链接

4. 测试您的设置

# 测试增强功能
python tests/test_enhanced_features.py

# 启动增强的MCP服务器
python -m src.main

5. 配置Claude Desktop

添加到您的Claude Desktop配置：

{
  "mcpServers": {
    "pfsense-enhanced": {
      "command": "python",
      "args": ["/path/to/pfsense-mcp-server/main_enhanced_mcp.py"],
      "env": {
        "PFSENSE_URL": "https://your-pfsense.local",
        "PFSENSE_API_KEY": "your-api-key",
        "PFSENSE_VERSION": "CE_2_8_0",
        "ENABLE_HATEOAS": "false"
      }
    }
  }
}

🛠️ 增强的MCP工具

🔍 搜索与发现

  • search_interfaces() - 使用高级过滤查找接口
  • search_firewall_rules() - 多字段规则搜索，支持分页
  • search_aliases() - 智能别名发现
  • search_dhcp_leases() - DHCP租约管理，支持状态过滤
  • find_blocked_rules() - 查找跨接口的阻塞规则

🛡️ 高级防火墙管理

  • create_firewall_rule_advanced() - 创建规则，支持位置控制
  • move_firewall_rule() - 动态重新排序规则
  • bulk_block_ips() - 高效地阻止多个IP
  • manage_alias_addresses() - 添加/删除别名条目
  • analyze_blocked_traffic() - 模式分析和威胁评分

📊 增强监控

  • search_logs_by_ip() - IP特定的日志分析
  • get_api_capabilities() - 发现API特性
  • follow_api_link() - 动态导航HATEOAS链接
  • refresh_object_ids() - 处理动态ID变化
  • find_object_by_field() - 基于字段的对象查找

⚙️ 对象与ID管理

  • enable_hateoas() / disable_hateoas() - 控制导航链接
  • test_enhanced_connection() - 综合连接性测试

💬 增强示例提示

"搜索WAN接口上阻止端口22的防火墙规则"
"显示过去24小时内的阻塞流量模式"
"查找所有包含IP 192.168.1.100的别名"
"阻止这些可疑IP：198.51.100.1, 203.0.113.1"
"搜索DHCP租约中的主机名包含'server'"
"将防火墙规则ID 5移动到位置1"
"分析阻塞流量并按源IP分组"
"查找当前处于关闭状态的接口"
"搜索描述中包含'malware'的防火墙规则"
"显示前10个被阻塞的源IP"

📚 文档

📖 安装指南

🔧 技术文档

🚀 部署

🧪 测试

# 测试基本API连接
python test_pfsense_api_v2.py

# 测试所有增强功能
python test_enhanced_features.py

# 运行综合测试套件
pytest tests/ -v

# 测试特定MCP工具
python -c "
import asyncio
from main_enhanced_mcp import search_firewall_rules
print(asyncio.run(search_firewall_rules(interface='wan', page_size=5)))
"

🏗️ 架构

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Claude Desktop │────│ 增强型MCP        │────│ pfSense API v2  │
│   (自然语言)     │    │ 服务器(Python)   │    │ (REST/GraphQL)  │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │                        │
                                ▼                        ▼
                       ┌──────────────────┐    ┌─────────────────┐
                       │ 高级功能          │    │ pfSense系统      │
                       │ • 过滤            │    │ • 防火墙          │
                       │ • 分页            │    │ • 接口            │
                       │ • HATEOAS         │    │ • 服务            │
                       │ • 对象ID          │    │ • DHCP/VPN        │
                       └──────────────────┘    └─────────────────┘

🤝 社区与贡献

🌟 我们需要您的帮助！

这个MCP服务器代表了pfSense自动化的重要进步，但我们还需要社区的帮助使其变得更好！无论您是pfSense老手、Python开发者还是GenAI爱好者，都有很多方式可以做出贡献。

🎯 如何帮助

🧪 Beta测试与反馈

  • 在您的环境中测试：尝试增强型MCP服务器与您的pfSense设置
  • 报告兼容性：告诉我们哪些pfSense版本工作正常（以及哪些不正常）
  • 分享使用案例：告诉我们您如何在实际场景中使用MCP工具
  • 性能反馈：帮助我们优化不同网络规模和配置下的性能

🐛 错误报告与问题

  • 发现了一个错误？ 打开一个issue，提供详细的重现步骤
  • 缺少的功能？ 建议新的MCP工具或API集成
  • 文档不清楚？ 帮助我们改进指南和示例

💻 代码贡献

  • 新的MCP工具：为pfSense包（如HAProxy、Suricata等）添加工具
  • 增强过滤：改进搜索和发现能力
  • 性能优化：帮助使服务器更快更高效
  • 测试覆盖：为边缘案例添加全面测试

📚 文档与示例

  • 真实世界示例：分享在Claude中工作的提示
  • 集成指南：如何与其他工具和工作流一起使用
  • 视频教程：创建设置和使用演示
  • 翻译：帮助将文档翻译成其他语言

🚀 作为贡献者入门

  1. 🍴 分叉仓库 并创建一个功能分支
  2. 🧪 测试您的更改 使用综合测试套件
  3. 📝 更新文档 为任何新功能
  4. 🔄 提交pull请求 并附带清晰的描述

💡 贡献想法

🎯 高优先级

  • 支持额外的pfSense包（如Snort、ntopng、FreeRADIUS）
  • 增强的安全分析工具
  • 备份和恢复自动化
  • 多实例pfSense管理

🔧 技术改进

  • GraphQL API集成
  • WebSocket实时更新
  • 高级缓存策略
  • 性能分析工具

🎨 用户体验

  • 自然语言查询改进
  • Claude Desktop界面增强
  • 基于Web的配置UI
  • 移动友好工具

🏆 认可

贡献者将：

  • 在我们的贡献者部分列出
  • 在发布说明中获得信用
  • 获得优先支持 用于他们自己的部署
  • 受邀加入贡献者Discord 以便直接协作

📢 保持联系

  • GitHub讨论：分享想法和提问
  • 问题：报告错误和请求功能
  • 拉取请求：贡献代码和文档
  • 发行版：关注更新和新功能

通过自然语言，我们可以让pfSense自动化对每个人来说都易于访问！🌟

"最好的开源项目是由社区构建的，而不是个人。您的贡献，无论大小，都会产生影响！"

📊 功能比较

功能基础MCP增强型MCP优点
API集成只支持XML-RPCREST API v2 + 回退现代化、更快、更可靠
过滤基本查询8种过滤类型 + 正则表达式找到你需要的确切内容
分页无智能分页处理大数据集
对象管理静态ID动态ID处理抵抗变化
导航手动端点HATEOAS链接发现API能力
控制基本操作细粒度参数精确的操作控制
性能基本缓存高级优化更快的响应时间

🔒 安全考虑

  • 🔐 认证：多种方法支持，带权限检查
  • 🛡️ 输入验证：所有用户输入均经过验证和清理
  • 🔍 审计日志：全面活动跟踪
  • 🚫 速率限制：防止滥用
  • 🔒 SSL/TLS：强制加密通信
  • 👤 权限管理：基于角色的访问控制

📈 性能与可扩展性

  • ⚡ 异步操作：非阻塞I/O，提高性能
  • 💾 智能缓存：减少API调用，智能缓存
  • 🔄 连接池：有效资源利用
  • 📊 分页：高效处理大数据集
  • 🎯 目标查询：高级过滤减少数据传输
  • 📈 指标：内置监控和性能追踪

🆘 支持与故障排除

常见问题

  1. 连接失败：检查pfSense API包是否已安装
  2. 身份验证错误：验证API密钥和用户权限
  3. 权限被拒绝：确保用户具有所需的pfSense权限
  4. 过滤不起作用：检查过滤语法和字段名称
  5. 性能慢：启用缓存并优化查询

获取帮助

  • 📖 文档：查看我们的综合指南
  • 🐛 问题：搜索现有问题或创建一个新的
  • 💬 讨论：在GitHub讨论中提问
  • 📧 支持：通过GitHub获得社区支持

📝 更新日志

v4.0.0 - 增强API集成

  • ✨ 完整支持pfSense REST API v2
  • 🔍 带8种运算符的高级过滤
  • 📊 智能分页和排序
  • 🔗 HATEOAS导航支持
  • ⚙️ 控制参数实现
  • 🆔 动态对象ID管理
  • 🛠️ 25+增强型MCP工具
  • 📚 综合文档

v3.0.0 - FastMCP集成

  • 🚀 迁移到FastMCP框架
  • 🔧 改进工具组织
  • 📈 更好的性能和可靠性

v2.0.0 - 生产就绪

  • 🐳 Docker部署支持
  • 🔒 安全加固
  • 📊 监控和指标

v1.0.0 - 初始发布

  • 🎯 基础MCP功能
  • 🔌 XML-RPC集成
  • 🛠️ 核心pfSense工具

📄 许可证

MIT许可证 - 详情见LICENSE。

🙏 致谢