pfSense Enhanced MCP Server

pfSense增强型MCP服务器

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

🧪 需要社区测试

⚠️ 重要： 这个项目需要社区测试和验证！\ 👥 我们需要您的帮助，在真实的pfSense设备和环境中测试这一点。 - 🔍 测试IT 使用pfSense设置 - 🐛 报告问题 通过GitHub问题 - 🔧 修复bug 并提交PR - 📝 改进文档 基于实际使用情况 - 💡 贡献功能 以及增强功能 您的测试和贡献将有助于为每个人准备好这部作品！

](https://github.com/gensecaihq/pfsense-mcp-server)    

✨ 增强功能

🎯 核心能力

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

🏢 企业就绪

• 🔒 多身份验证支持：API密钥、基本身份验证、JWT和安全最佳实践
• 📈 生产监控：健康检查、指标、审计日志
• 🐳 集装箱准备就绪：具有安全强化功能的Docker部署
• 🎨 25+MCP工具：全面的pfSense管理功能
• ⚡ 高性能：异步操作、缓存、连接池

🎮 支持的pfSense版本

🚀 快速开始

1.安装pfSense REST API包

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

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

# For 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. 引导到 系统→ REST API 在pfSense网络配置工具中
2. 启用REST API
3. 生成API密钥： 系统→ 用户管理器→ \[您的用户\]→ API密钥
4. 为API用户分配适当的权限

3.设置MCP服务器

# Clone the repository
git clone https://github.com/gensecaihq/pfsense-mcp-server.git
cd pfsense-mcp-server

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
nano .env  # Add your pfSense details

最小化 .env 配置：

PFSENSE_URL=https://your-pfsense.local
PFSENSE_API_KEY=your-api-key-here
PFSENSE_VERSION=CE_2_8_0  # or PLUS_24_11
AUTH_METHOD=api_key
VERIFY_SSL=true
ENABLE_HATEOAS=false  # Set true for navigation links

4.测试您的设置

# Test enhanced features
python tests/test_enhanced_features.py

# Start the enhanced MCP server
python -m src.main

5.配置克劳德桌面

添加到您的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() -全面的连接测试

💬 增强示例提示

"Search for firewall rules on WAN interface blocking port 22"
"Show me blocked traffic patterns from the last 24 hours"
"Find all aliases containing IP 192.168.1.100"
"Block these suspicious IPs: 198.51.100.1, 203.0.113.1"
"Search DHCP leases for hostname containing 'server'"
"Move firewall rule ID 5 to position 1"
"Analyze blocked traffic and group by source IP"
"Find interfaces that are currently down"
"Search for firewall rules with 'malware' in description"
"Show me the top 10 blocked source IPs"

📚 文档

📖 设置指南

• pfSense API安装指南 -完整的设置说明
• 增强功能指南 -高级功能概述
• 配置参考 -所有环境变量

🔧 技术文档

• API集成详细信息 -增强型API的工作原理
• MCP工具参考 -完整的工具文档
• 故障排除指南 -常见问题和解决方案

🚀 部署

• **** -容器设置
• 生产指南 -企业部署
• 安全最佳实践 -硬化指南

🧪 测试

# Test basic API connection
python test_pfsense_api_v2.py

# Test all enhanced features
python test_enhanced_features.py

# Run comprehensive test suite
pytest tests/ -v

# Test specific MCP tools
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 │────│ Enhanced MCP     │────│ pfSense API v2  │
│   (Natural Lang) │    │ Server (Python)  │    │ (REST/GraphQL)  │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │                        │
                                ▼                        ▼
                       ┌──────────────────┐    ┌─────────────────┐
                       │ Advanced Features │    │ pfSense System  │
                       │ • Filtering       │    │ • Firewall      │
                       │ • Pagination      │    │ • Interfaces    │
                       │ • HATEOAS         │    │ • Services      │
                       │ • Object IDs      │    │ • DHCP/VPN      │
                       └──────────────────┘    └─────────────────┘

🤝 社区与贡献

🌟 我们需要您的帮助！

此MCP服务器代表了pfSense自动化的重大进步，但 我们需要社区的帮助，让它变得更好！无论你是pfSense老手、Python开发人员还是GenAI爱好者，都有很多方法可以做出贡献。

🎯 您如何提供帮助

🧪 Beta测试和反馈

• 在您的环境中进行测试：使用pfSense设置尝试增强型MCP服务器
• 报告兼容性：让我们知道哪些适用于不同的pfSense版本（哪些不适用）
• 共享用例：告诉我们您在实际场景中是如何使用MCP工具的
• 绩效反馈：帮助我们针对不同的网络规模和配置进行优化

🐛 Bug报告和问题

• 发现bug了吗？ 打开一个问题 具有详细的复制步骤
• 缺少功能？ 建议新的MCP工具或API集成
• 文件不清楚？ 帮助我们改进指南和示例

💻 代码贡献

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

📚 文档和示例

• 真实世界的例子：分享克劳德的提示，效果很好
• 集成指南：如何与其他工具和工作流一起使用
• 视频教程：创建设置和使用演示
• 翻译：帮助以其他语言访问文档

🚀 作为贡献者入门

1. 🍴 分叉存储库 并创建一个特征分支
2. 🧪 测试您的更改 使用全面的测试套件
3. 📝 更新文档 对于任何新功能
4. 🔄 提交拉取请求 描述清晰

💡 贡献的想法

🎯 高优先级

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

🔧 技术改进

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

🎨 用户体验

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

🏆 认可

贡献者将是：

• 在我们的贡献者部分列出
• 记入发行说明
• 给予优先支持 用于他们自己的部署
• 受邀加入贡献者Discord 直接合作

📢 保持联系

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

我们可以通过自然语言让每个人都能使用pfSense自动化！ 🌟

______________________________________________________________________

*“最好的开源项目是由社区而不是个人构建的。你的贡献，无论多小，都会产生影响！”*

📊 功能对比

🔒 安全考虑

• 🔐 认证：具有权限检查的多方法支持
• 🛡️ 输入验证：所有用户输入都经过验证和消毒
• 🔍 审计日志：全面的活动跟踪
• 🚫 速率限制：防止虐待
• 🔒 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-快速MCP集成

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

v2.0.0-生产就绪

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

v1.0.0-初始版本

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

📄 许可证

MIT许可证-请参阅 许可证 了解详情。

______________________________________________________________________

🙏 致谢

• 贾里德·亨德里克森13 用于优秀的pfSense REST API软件包
• Anthropic 模型上下文协议和Claude
• Netgate 对于pfSense
• FastMCP 对于MCP框架
• 社区贡献者 用于测试、反馈和改进

______________________________________________________________________

⭐ 如果此仓库能帮助您使用AI管理pfSense，请将其标记为星号！ ⭐

由以下材料制成❤️ 为社区，为社区