Supports containerized deployment for easy installation and management of the MCP server.
Enables natural language control of pfSense firewalls with multiple access levels for monitoring, security rule modification, system administration, compliance auditing, and emergency response.
pfSense Enhanced MCP Server
🚀 A next-generation Model Context Protocol (MCP) server that enables natural language interaction with pfSense firewalls through Claude Desktop and other GenAI applications. Now with advanced API features by pfrest.org including intelligent filtering, HATEOAS navigation, and enterprise-grade controls.
🧪 Community Testing Needed
⚠️ IMPORTANT: This project needs community testing and validation!
👥 We need your help to test this with real pfSense devices and environments.
- 🔍 Test it with your pfSense setup
- 🐛 Report issues via GitHub Issues
- 🔧 Fix bugs and submit PRs
- 📝 Improve documentation based on real-world usage
- 💡 Contribute features and enhancements
Your testing and contributions will help make this production-ready for everyone!
✨ Enhanced Features
🎯 Core Capabilities
- 🗣️ Natural Language Interface: Control pfSense using plain English with Claude
- 🔧 Advanced API Integration: Full support for jaredhendrickson13/pfsense-api v2
- 🔍 Intelligent Filtering: 8 filter types (exact, contains, regex, ranges) with multi-field support
- 📊 Smart Pagination: Efficient handling of large datasets with sorting
- 🔗 HATEOAS Navigation: Dynamic API exploration with hypermedia controls
- ⚙️ Control Parameters: Fine-grained operation control (apply, async, placement)
- 🆔 Object ID Management: Handles dynamic IDs with field-based lookups
🏢 Enterprise Ready
- 🔒 Multi-Auth Support: API Key, Basic Auth, JWT with security best practices
- 📈 Production Monitoring: Health checks, metrics, audit logging
- 🐳 Container Ready: Docker deployment with security hardening
- 🎨 25+ MCP Tools: Comprehensive pfSense management capabilities
- ⚡ High Performance: Async operations, caching, connection pooling
🎮 Supported pfSense Versions
Version | Status | API Package | Features |
---|---|---|---|
pfSense CE 2.8.0 | ✅ Fully Supported | Download | All enhanced features |
pfSense Plus 24.11 | ✅ Fully Supported | Download | All enhanced features |
🚀 Quick Start
1. Install pfSense REST API Package
On your pfSense system (via SSH or console):
2. Configure pfSense API
- Navigate to System → REST API in pfSense webConfigurator
- Enable the REST API
- Generate an API key: System → User Manager → [Your User] → API Keys
- Assign appropriate privileges to your API user
3. Setup MCP Server
Minimal .env
configuration:
4. Test Your Setup
5. Configure Claude Desktop
Add to your Claude Desktop configuration:
🛠️ Enhanced MCP Tools
🔍 Search & Discovery
search_interfaces()
- Find interfaces with advanced filteringsearch_firewall_rules()
- Multi-field rule search with paginationsearch_aliases()
- Intelligent alias discoverysearch_dhcp_leases()
- DHCP lease management with state filteringfind_blocked_rules()
- Locate blocking rules across interfaces
🛡️ Advanced Firewall Management
create_firewall_rule_advanced()
- Create rules with position controlmove_firewall_rule()
- Reorder rules dynamicallybulk_block_ips()
- Block multiple IPs efficientlymanage_alias_addresses()
- Add/remove alias entriesanalyze_blocked_traffic()
- Pattern analysis and threat scoring
📊 Enhanced Monitoring
search_logs_by_ip()
- IP-specific log analysisget_api_capabilities()
- Discover API featuresfollow_api_link()
- Navigate HATEOAS links dynamicallyrefresh_object_ids()
- Handle dynamic ID changesfind_object_by_field()
- Field-based object lookup
⚙️ Object & ID Management
enable_hateoas()
/disable_hateoas()
- Control navigation linkstest_enhanced_connection()
- Comprehensive connectivity testing
💬 Enhanced Example Prompts
📚 Documentation
📖 Setup Guides
- pfSense API Installation Guide - Complete setup instructions
- Enhanced Features Guide - Advanced capabilities overview
- Configuration Reference - All environment variables
🔧 Technical Documentation
- API Integration Details - How the enhanced API works
- MCP Tools Reference - Complete tool documentation
- Troubleshooting Guide - Common issues and solutions
🚀 Deployment
- Docker Deployment - Container setup
- Production Guide - Enterprise deployment
- Security Best Practices - Hardening guidelines
🧪 Testing
🏗️ Architecture
🤝 Community & Contributions
🌟 We Need Your Help!
This MCP server represents a significant advancement in pfSense automation, but we need the community to help make it even better! Whether you're a pfSense veteran, Python developer, or GenAI enthusiast, there are many ways to contribute.
🎯 How You Can Help
🧪 Beta Testing & Feedback
- Test in your environment: Try the enhanced MCP server with your pfSense setup
- Report compatibility: Let us know what works (and what doesn't) with different pfSense versions
- Share use cases: Tell us how you're using the MCP tools in real scenarios
- Performance feedback: Help us optimize for different network sizes and configurations
🐛 Bug Reports & Issues
- Found a bug? Open an issue with detailed reproduction steps
- Missing feature? Suggest new MCP tools or API integrations
- Documentation unclear? Help us improve the guides and examples
💻 Code Contributions
- New MCP tools: Add tools for pfSense packages (HAProxy, Suricata, etc.)
- Enhanced filtering: Improve search and discovery capabilities
- Performance optimizations: Help make the server faster and more efficient
- Test coverage: Add comprehensive tests for edge cases
📚 Documentation & Examples
- Real-world examples: Share Claude prompts that work well
- Integration guides: How to use with other tools and workflows
- Video tutorials: Create setup and usage demonstrations
- Translation: Help make documentation accessible in other languages
🚀 Getting Started as a Contributor
- 🍴 Fork the repository and create a feature branch
- 🧪 Test your changes with the comprehensive test suite
- 📝 Update documentation for any new features
- 🔄 Submit a pull request with a clear description
💡 Ideas for Contributions
🎯 High Priority
- Support for additional pfSense packages (Snort, ntopng, FreeRADIUS)
- Enhanced security analysis tools
- Backup and restore automation
- Multi-pfSense instance management
🔧 Technical Improvements
- GraphQL API integration
- WebSocket real-time updates
- Advanced caching strategies
- Performance profiling tools
🎨 User Experience
- Natural language query improvements
- Claude Desktop interface enhancements
- Web-based configuration UI
- Mobile-friendly tools
🏆 Recognition
Contributors will be:
- Listed in our contributors section
- Credited in release notes
- Given priority support for their own deployments
- Invited to the contributor Discord for direct collaboration
📢 Stay Connected
- GitHub Discussions: Share ideas and ask questions
- Issues: Report bugs and request features
- Pull Requests: Contribute code and documentation
- Releases: Follow for updates and new features
Together, we can make pfSense automation accessible to everyone through natural language! 🌟
"The best open source projects are built by communities, not individuals. Your contribution, no matter how small, makes a difference!"
📊 Feature Comparison
Feature | Basic MCP | Enhanced MCP | Benefits |
---|---|---|---|
API Integration | XML-RPC only | REST API v2 + fallbacks | Modern, faster, more reliable |
Filtering | Basic queries | 8 filter types + regex | Find exactly what you need |
Pagination | None | Smart pagination | Handle large datasets |
Object Management | Static IDs | Dynamic ID handling | Robust against changes |
Navigation | Manual endpoints | HATEOAS links | Discover API capabilities |
Controls | Basic operations | Fine-grained parameters | Precise operation control |
Performance | Basic caching | Advanced optimization | Faster response times |
🔒 Security Considerations
- 🔐 Authentication: Multi-method support with privilege checking
- 🛡️ Input Validation: All user inputs validated and sanitized
- 🔍 Audit Logging: Comprehensive activity tracking
- 🚫 Rate Limiting: Protection against abuse
- 🔒 SSL/TLS: Encrypted communication enforced
- 👤 Privilege Management: Role-based access control
📈 Performance & Scalability
- ⚡ Async Operations: Non-blocking I/O for better performance
- 💾 Intelligent Caching: Reduce API calls with smart caching
- 🔄 Connection Pooling: Efficient resource utilization
- 📊 Pagination: Handle large datasets efficiently
- 🎯 Targeted Queries: Advanced filtering reduces data transfer
- 📈 Metrics: Built-in monitoring and performance tracking
🆘 Support & Troubleshooting
Common Issues
- Connection Failed: Check pfSense API package installation
- Authentication Error: Verify API key and user privileges
- Permission Denied: Ensure user has required pfSense privileges
- Filter Not Working: Check filter syntax and field names
- Slow Performance: Enable caching and optimize queries
Getting Help
- 📖 Documentation: Check our comprehensive guides
- 🐛 Issues: Search existing issues or create a new one
- 💬 Discussions: Ask questions in GitHub Discussions
- 📧 Support: Community support through GitHub
📝 Changelog
v4.0.0 - Enhanced API Integration
- ✨ Full pfSense REST API v2 support
- 🔍 Advanced filtering with 8 operators
- 📊 Smart pagination and sorting
- 🔗 HATEOAS navigation support
- ⚙️ Control parameters implementation
- 🆔 Dynamic object ID management
- 🛠️ 25+ enhanced MCP tools
- 📚 Comprehensive documentation
v3.0.0 - FastMCP Integration
- 🚀 Migrated to FastMCP framework
- 🔧 Improved tool organization
- 📈 Better performance and reliability
v2.0.0 - Production Ready
- 🐳 Docker deployment support
- 🔒 Security hardening
- 📊 Monitoring and metrics
v1.0.0 - Initial Release
- 🎯 Basic MCP functionality
- 🔌 XML-RPC integration
- 🛠️ Core pfSense tools
📄 License
MIT License - see LICENSE for details.
🙏 Acknowledgments
- jaredhendrickson13 for the excellent pfSense REST API package
- Anthropic for the Model Context Protocol and Claude
- Netgate for pfSense
- FastMCP for the MCP framework
- Community contributors for testing, feedback, and improvements
⭐ Star this repo if it helps you manage pfSense with AI! ⭐
Made with ❤️ by the community, for the community
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
A production-grade server that enables natural language interaction with pfSense firewalls through Claude Desktop and other GenAI applications, supporting multiple access levels and functional categories.
- 🧪 Community Testing Needed
- ✨ Enhanced Features
- 🚀 Quick Start
- 🛠️ Enhanced MCP Tools
- 💬 Enhanced Example Prompts
- 📚 Documentation
- 🧪 Testing
- 🏗️ Architecture
- 🤝 Community & Contributions
- 📊 Feature Comparison
- 🔒 Security Considerations
- 📈 Performance & Scalability
- 🆘 Support & Troubleshooting
- 📝 Changelog
- 📄 License
- 🙏 Acknowledgments
Related MCP Servers
- AsecurityFlicenseAqualityThe server facilitates natural language interactions for exploring and understanding codebases, providing insights into data models and system architecture using a cost-effective, simple setup with support for existing Claude Pro subscriptions.Last updated -418
- AsecurityAlicenseAqualityA server implementation that enables natural language interactions with UniFi network devices by wrapping the UniFi Network API for AI agents like Goose and Claude.Last updated -2MIT License
- -securityAlicense-qualityA server that integrates Confluence with Claude Desktop and other AI assistants, enabling natural language interactions with your Confluence documentation.Last updated -1MIT License
- AsecurityAlicenseAqualityA server that enables managing OPNSense firewalls through natural language interactions with Claude Desktop, supporting VLAN management, firewall rules configuration, and network interface queries.Last updated -64816MIT License