🔥 OPNsense MCP Server

🚀 Transform your OPNsense firewall management with AI-powered natural language commands!

⚠️ CRITICAL: Security & Usage Disclaimer

🚨 THIS TOOL SHOULD NEVER BE USED IN PRODUCTION ENVIRONMENTS 🚨

⛔ Production Use: STRICTLY PROHIBITED

This project is ONLY for:

• 🧪 Laboratory environments - Isolated test networks

• 📚 Educational purposes - Learning about AI and network automation

• 🔬 Experimentation - Exploring agentic AI capabilities

• 🎯 Research - Understanding AI-controlled infrastructure

This project is NOT for:

• ❌ Production firewalls (business or personal)

• ❌ Any environment where downtime matters

• ❌ Networks protecting real assets or data

• ❌ Internet-facing or critical infrastructure

🤖 Why This Restriction?

Large Language Models (LLMs) are fundamentally unpredictable:

1. Non-Deterministic Behavior

   • Same prompt can produce different results

   • No guarantees on output correctness

   • Can hallucinate configurations that seem correct but aren't

2. Firewall Management is Critical

   • Mistakes expose your network to attacks

   • Misconfigurations can block all traffic

   • Recovery may require physical console access

   • Security implications are severe

3. AI Technology Maturity

   • Current state (2025): Powerful but unreliable for critical systems

   • LLMs can confidently give wrong answers

   • Intent interpretation is imperfect

   • No formal verification of outputs

Example risks:

• "Block suspicious traffic" → Blocks everything

• "Open port for SSH" → Exposes unintended services

• "Configure VPN" → Creates insecure tunnel

• AI hallucinates non-existent APIs or parameters

🎓 Intended Audience

This project is for curious professionals and enthusiasts who want to explore:

• How AI agents interact with network equipment

• Capabilities and limitations of LLM-driven automation

• Future possibilities of AI in infrastructure management

• Natural language interfaces for complex systems

You should:

• Have networking knowledge to recognize bad configurations

• Use completely isolated lab environments

• Understand you're experimenting with emerging technology

• Be prepared for unexpected behaviors and errors

🏠 Recommended: Self-Hosted LLMs

For maximum safety and privacy, use local LLMs like

Why local models:

• 🔒 Privacy: Network configurations never leave your lab

• 🎛️ Control: Specific model versions, reproducible behavior

• 💰 Cost: No API fees

• 📡 Offline: No internet dependency

• 🔍 Transparency: Inspect and modify model behavior

Setup with Ollama:

Note: Even with local models, use ONLY in lab environments. The unpredictability comes from the AI technology itself, not the hosting method.

🤖 AI-Generated Code Transparency

This codebase was created with AI assistance:

• 🔧 ~90% generated using Claude Code

• 👁️ Reviewed by both AI agents and humans

• ✅ Tested with 296+ automated tests (100% pass rate)

• 📋 Security audited for credential handling

What this means:

• ✅ Rapid development of complex functionality

• ⚠️ Possible bugs despite thorough review

• 🔍 Complete transparency about code origin

• 🧪 Your responsibility to test before trusting

Both AI reviewers and humans can miss issues. Treat this code as you would any open-source project: inspect it, test it thoroughly in safe environments, and report issues.

🛡️ Safety Guidelines for Lab Use

If using in your lab environment:

1. Isolation is Critical

   • Use completely separate networks

   • No connection to production systems

   • Preferably virtual environments (VMs, containers)

   • Air-gapped from sensitive data

2. Backup Before Every Change

   • Export OPNsense configuration before experiments

   • Test backup restoration procedures

   • Keep multiple backup generations

3. Monitor Everything

   • Watch firewall logs in real-time

   • Set up alerts for unexpected changes

   • Have console access ready for recovery

4. Start with Read-Only

   • Begin with status queries and information gathering

   • Review code for write operations before enabling

   • Gradually increase complexity as you understand behavior

5. Expect Failures

   • AI will make mistakes - plan for it

   • Have rollback procedures documented

   • Know how to recover from console if locked out

   • Consider it a learning experience, not a reliable tool

6. Never Trust, Always Verify

   • Review every AI suggestion before applying

   • Understand what changes will do

   • Check for unintended side effects

   • Use dry-run modes when available

🔮 Future of AI Infrastructure Management

This project explores the future, not the present:

We're in the early experimental phase of AI-controlled infrastructure. This technology will mature, but today:

• ❌ Not reliable enough for production

• ✅ Excellent for research and learning

• 🔬 Helps identify what's needed for production-readiness

Future developments needed:

• Formal verification of AI outputs

• Deterministic reasoning for critical operations

• Sandbox/simulation modes

• Safety guardrails and constraints

• Specialized models trained on network operations

By experimenting responsibly in labs, you contribute to understanding how this technology should evolve.

⚖️ Legal Disclaimer

BY USING THIS SOFTWARE YOU ACKNOWLEDGE:

• This is experimental software for laboratory use only

• Authors assume NO responsibility for damages, outages, or security breaches

• You accept ALL risk when running this on any firewall

• Production use violates the intended purpose of this project

• You will not hold authors liable for any consequences

Use at your own risk. You have been warned.

📞 Questions or Report Issues?

• 📖 Security best practices: SECURITY.md

• 🐛 Report bugs: GitHub Issues

• 💬 Discuss: GitHub Discussions

Remember: This is a research project for curious professionals exploring AI capabilities in network automation. Keep it in the lab.

🎯 Quick Example: "Block all traffic from Russia and add those IPs to my threat list" → Done! ✅

OPNsense® is a powerful open-source firewall and routing platform built on FreeBSD. This project transforms traditional firewall management by enabling natural language control through AI clients like Claude Desktop. Simply speak to your firewall as you would to a network engineer, and watch complex configurations happen automatically!

🎉 What makes this special? Instead of clicking through web interfaces or memorizing API commands, just say:

• "Show me what's using the most bandwidth" 📊

• "Create a VPN user for my remote developer" 👥

• "Block suspicious traffic and generate a security report" 🛡️

⚡ Quick Start (5 minutes)

🎊 That's it! You're now managing your firewall with natural language!

🔒 Security Note: Your credentials are stored locally in ~/.opnsense-mcp/config.json with secure permissions (0600). They are never sent to Claude or any AI model. See SECURITY.md for details.

🧠 What is an MCP Server? Why Is It a Game Changer for AI?

The Model Context Protocol (MCP) is a new standard that lets AI models (like Claude, ChatGPT, and others) securely interact with real-world tools, data, and systems—not just answer questions, but actually take action. You can think of it as "giving hands to the brain": the AI is the brain, and the MCP server is the set of hands that can reach out and do things in the real world. For more technical details, refer to the official MCP specification.

🌟 Why is this revolutionary?

• 🎯 From Answers to Actions: Traditional AI models only provide information. With MCP, they actually perform tasks—like managing your firewall, configuring VPNs, or analyzing security logs—by calling tools exposed by an MCP server.

• 🔒 Security and Trust: MCP is designed to be secure and auditable. You control exactly what the AI can access, and you can see every action it takes.

• 🔌 Plug-and-Play for AI Clients: Tools like Claude Desktop make it easy to connect to MCP servers. Just add the server in settings, and suddenly your AI can manage your OPNsense firewall!

• 🎭 Separation of Concerns: The AI doesn't need to know OPNsense APIs. The MCP server handles all the technical details, so you get automation power without security risks.

🚀 How does it work in practice?

1. 🏠 You run an MCP server (like this OPNsense MCP Server) on your machine or network

2. 🔗 You connect your AI client (like Claude Desktop) to the MCP server in settings

3. ⚡ The AI can now use the tools exposed by the server—securely, with your oversight

💡 The game changer: MCP servers let you safely delegate real-world network management tasks to AI, making your AI not just smart, but truly useful for infrastructure management!

🛠️ Complete Feature Set (166 Tools!)

🔌 Connection & Configuration

🖥️ System Management

🔥 Firewall Management

📝 Alias Management

🔄 NAT Management

🌐 Network Interface Management

🔗 VLAN Management

🌉 Bridge Management

⚡ Link Aggregation (LAGG)

🏷️ Virtual IP Management

📡 DHCP Server Management

📍 DHCP Static Mappings

🔍 DNS Resolver (Unbound)

⏩ DNS Forwarder (dnsmasq)

🔐 Certificate Authority Management

📜 Certificate Management

📋 Certificate Signing Requests

🔄 ACME (Let's Encrypt) Management

🔍 Certificate Analysis & Monitoring

👥 User Management

👨‍👩‍👧‍👦 Group Management

🛡️ Privilege Management

🔑 Authentication Systems

📊 Comprehensive Logging & Monitoring

🔌 Plugin & Service Management

🌐 VPN Connection Monitoring

🚦 Traffic Shaping & QoS Management

🔧 Pipe Management (Bandwidth Limits)

⚖️ Queue Management (Weighted Sharing)

📋 Rule Management (Traffic Classification)

🎯 Common QoS Use Cases (Helpers)

🔧 Advanced & Custom Tools

🎯 Total: 166 powerful tools for complete OPNsense management through natural language!

🌟 Real-World Success Stories

🏢 Enterprise Network Management

"We manage 50+ OPNsense firewalls across multiple sites. This MCP server lets our junior admins safely make changes using natural language, reducing configuration errors by 80% and training time by weeks!" - Network Operations Team

🚨 Incident Response

"During a security incident, I told Claude: 'Block all traffic from these suspicious IPs and create an audit report.' Done in 15 seconds instead of 5 minutes of clicking through interfaces!" - Security Engineer

📚 Learning & Training Tool

"Perfect for learning OPNsense! New team members can ask Claude to explain what each rule does before applying it. It's like having a network mentor available 24/7." - IT Training Manager

🏠 Home Lab Enthusiasts

"I can finally manage my home lab firewall properly without memorizing every interface. Just tell it what I want, and it handles the technical details!" - Home Lab Enthusiast

🎯 Try These Commands!

Perfect for getting started:

• "Show me the firewall status and health"

• "List all network interfaces and their status"

• "What devices are currently connected via DHCP?"

• "Show me recent firewall activity"

• "Create a backup of my configuration"

For network administrators:

• "Create a geo-blocking rule for all countries except USA and Canada"

• "Setup a VLAN for IoT devices with restricted internet access"

• "Analyze security logs and identify potential threats from the last 24 hours"

• "Create DHCP reservations for all devices in the server VLAN"

• "Generate SSL certificates for internal services using Let's Encrypt"

Advanced infrastructure management:

• "Create a high-availability CARP setup with automatic failover between firewalls"

• "Configure certificate-based VPN with automatic user provisioning and revocation"

• "Implement zero-trust network segmentation for the DMZ with micro-segmentation rules"

• "Setup automated threat response: block IPs with more than 10 failed attempts in 5 minutes"

• "Create a comprehensive security audit report with compliance recommendations"

📋 Requirements

• 🐍 Python 3.10+ (Modern Python environment)

• 🔥 OPNsense Firewall with API access configured

• 🤖 MCP-compatible client (Claude Desktop recommended)

• 💾 Minimum 100MB disk space for installation

📦 Prerequisites

• 🔧 git - For cloning the repository

• ⚡ uv - Ultra-fast Python package manager (see installation below)

• 🔨 jq - JSON processor (for automated Claude Desktop setup)

🚀 Installation Guide

Step 1: 📥 Clone the Repository

Step 2: ⚡ Install

uv is blazing fast and handles everything automatically:

Step 3: 🏠 Create Virtual Environment

Step 4: 📚 Install Dependencies

Step 5: 🔐 Make Scripts Executable (Linux/macOS only)

🎉 Installation Complete!

Time to configure your OPNsense connection...

🔐 Setup OPNsense API Access

📌 Important: Create dedicated API credentials for maximum security!

🔑 Step-by-Step API Setup:

1. 🌐 Login to your OPNsense web interface

2. 🧭 Navigate to System → Access → Users

3. 👤 Select the user for API access (or create a dedicated mcp-server user)

4. 🔑 Scroll down to the API keys section

5. ➕ Click the to generate new API keys

6. 📁 Download the API key file (contains your credentials)

💡 Pro Tip: Create a dedicated user with minimal required privileges instead of using admin credentials!

🤖 Configure Claude Desktop

Choose your preferred setup method:

🎯 Method 1: Auto-Magic Setup (Recommended)

The easiest way - one command does everything!

🎊 That's it! The script automatically:

• ✅ Finds your Claude Desktop config

• ✅ Smart Python detection - Uses virtual environment (.venv/bin/python) if available

• ✅ Safe configuration - Shows current vs new config before updating

• ✅ Automatic backups - Creates timestamped backups before any changes

• ✅ Existing config detection - Asks permission before overwriting existing entries

• ✅ Creates proper file paths

• ✅ Sets up everything perfectly

🔄 Restart Claude Desktop and you're ready to go!

🔧 Method 2: Manual Configuration

1. 📥 Install Claude Desktop if you haven't already

2. 🖥️ Open Claude Desktop

3. ⚙️ Access settings from the Claude menu

4. 🛠️ Go to the Developer tab

5. 📝 Click "Edit Config"

6. 🔧 Add this configuration (replace /path/to/ with your actual path):

7. 💾 Save the config file

8. 🔄 Restart Claude Desktop

🎮 Usage Examples

Now the fun begins! Talk to your firewall like you're talking to a network engineer:

🔌 First Steps: Connect to Your Firewall

📊 System Monitoring

🔥 Firewall Management

🌐 Network Configuration

🏷️ Alias Management

🔐 Certificate Management

📋 User Management

📊 Logging & Analysis

🛡️ Security Operations

🔧 Advanced Operations

💡 The magic: Just describe what you want in plain English, and watch your firewall configuration happen automatically!

🔒 Security Best Practices

✅ Recommended Security Setup

🛡️ Security Commands to Run Regularly

⚠️ Production Environment Guidelines

🚨 Critical for Production Systems:

🔒 Maximum Security Approach

• Disable Web GUI/API after initial setup on production firewalls

• Console Management via direct serial cable connection

• Configuration Staging in isolated lab environment first

🔄 Staging Workflow

1. 🧪 Configure in secure lab environment using MCP server

2. 🧪 Test all changes thoroughly

3. 📤 Export configuration (config.xml)

4. 🔒 Import to production firewall (running headless)

5. ✅ Verify via console that changes worked

⚖️ Risk Assessment

This MCP server provides powerful automation but requires API access. Carefully evaluate:

• 🎯 Threat Model: What are your specific risks?

• 🔍 Monitoring: Can you detect API abuse quickly?

• 🚫 Network Isolation: Is the management network properly segmented?

• 👥 Team Training: Do operators understand the security implications?

🔧 Troubleshooting

🚨 Common Issues & Quick Fixes

🔍 Diagnostic Commands

Use these commands to troubleshoot:

📋 Step-by-Step Troubleshooting

1. 🔍 Check Connection: curl -k https://YOUR_FIREWALL_IP/api/core/firmware/status

2. 🔑 Verify Credentials: Ensure API key/secret are correct

3. 🌐 Test Network: Can you access the web interface?

4. 🛠️ Check Permissions: Does the API user have required privileges?

5. 📱 Restart Services: Try restarting Claude Desktop

6. 📋 Check Logs: Look at Claude Desktop console for error messages

🧪 Testing

✅ Test Suite Status

The project includes a comprehensive test suite with 296 tests covering all core functionality:

Current Status: ✅ 296/296 tests passing (100%)

For detailed test results and coverage information, see TEST_RESULTS.md.

🔧 Development Testing

🤝 Contributing & Community

💡 Want to Contribute?

We love contributions! Here's how you can help:

• 🐛 Found a bug? Open an issue with details

• 💡 Have an idea? Submit a feature request

• 🔧 Fixed something? Create a pull request

• 📚 Improved docs? Documentation PRs are welcome!

• ⭐ Like the project? Give us a star on GitHub!

• ✅ All PRs must pass tests - Run pytest before submitting

See CONTRIBUTING.md for detailed contribution guidelines.

🌟 Community & Support

• 💬 Discussions: Share ideas and get help

• 🐛 Issues: Report bugs and request features

• 📧 Questions: Ask anything about OPNsense + MCP integration

• 🎉 Showcase: Share your automation success stories!

📚 References & Acknowledgements

🔥 OPNsense®

This project interfaces with OPNsense firewalls - a powerful open source, FreeBSD-based firewall and routing platform.

• 🌐 Website: OPNsense.org

• 📖 API Documentation: OPNsense API Guide

🤖 Anthropic & Model Context Protocol (MCP)

This server implements MCP to enable AI-powered firewall management through Claude Desktop.

• 📖 MCP Specification: Official MCP Docs

• 🔧 Claude Tool Use: Anthropic Tool Documentation

🎨 AI Assistance

The project logo and portions of the codebase were created with AI assistance, demonstrating the collaborative future of software development.

📜 License

This project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details.

📌 What this means:

• ✅ Free to use for personal and commercial projects

• ✅ Modify and distribute under the same license

• ✅ Network use requires sharing source code modifications

• ✅ Patent protection included

🙏 Star History & Recognition

If this project helped you manage your OPNsense firewall more effectively, please consider giving it a ⭐ on GitHub!

Together, we're making network management more accessible through AI! 🚀