A Model Context Protocol (MCP) server for comprehensive OPNsense firewall management. This server enables AI assistants like Claude to directly manage firewall configurations, diagnose network issues, and automate complex networking tasks. - Complete CRUD operations for firewall rules - Proper handling of API-created "automation rules" - Inter-VLAN routing configuration - Batch rule creation and m
Add this skill
npx mdskills install vespo92/opnsensemcpComprehensive MCP server with 50+ well-documented tools for OPNsense firewall management and diagnostics
1# OPNsense MCP Server23[](https://www.npmjs.com/package/opnsense-mcp-server)4[](https://opensource.org/licenses/MIT)56A Model Context Protocol (MCP) server for comprehensive OPNsense firewall management. This server enables AI assistants like Claude to directly manage firewall configurations, diagnose network issues, and automate complex networking tasks.78## Features910### 🔥 Firewall Management11- Complete CRUD operations for firewall rules12- Proper handling of API-created "automation rules"13- Inter-VLAN routing configuration14- Batch rule creation and management15- Enhanced persistence with multiple fallback methods1617### 🌐 NAT Configuration (SSH-based)18- Outbound NAT rule management19- NAT mode control (automatic/hybrid/manual/disabled)20- No-NAT exception rules for inter-VLAN traffic21- Automated DMZ NAT issue resolution22- Direct XML configuration manipulation2324### 🔍 Network Diagnostics25- Comprehensive routing analysis26- ARP table inspection with vendor identification27- Interface configuration management28- Network connectivity troubleshooting29- Auto-fix capabilities for common issues3031### 🖥️ SSH/CLI Execution32- Direct command execution on OPNsense33- Configuration file manipulation34- System-level operations not available via API35- Service management and restarts3637### 📊 Additional Capabilities38- VLAN management39- DHCP lease viewing and management40- DNS blocklist configuration41- HAProxy load balancer support42- Configuration backup and restore43- Infrastructure as Code support4445## Installation4647### Prerequisites48- Node.js 18+ or Bun 1.0+49- OPNsense firewall (v24.7+ recommended)50- API credentials for OPNsense51- SSH access (optional, for advanced features)5253### Quick Start with npm54551. Install the package:56```bash57npm install -g opnsense-mcp-server58```59602. Create a `.env` file with your credentials:61```bash62# Required63OPNSENSE_HOST=https://your-opnsense-host:port64OPNSENSE_API_KEY=your-api-key65OPNSENSE_API_SECRET=your-api-secret66OPNSENSE_VERIFY_SSL=false6768# Optional - for SSH features69OPNSENSE_SSH_HOST=your-opnsense-host70OPNSENSE_SSH_USERNAME=root71OPNSENSE_SSH_PASSWORD=your-password72# Or use SSH key73# OPNSENSE_SSH_KEY_PATH=~/.ssh/id_rsa74```75763. Start the MCP server:77```bash78opnsense-mcp-server79```8081### Quick Start with Bun (Faster)8283[Bun](https://bun.sh) provides significantly faster startup times and better performance.84851. Install Bun (if not already installed):86```bash87curl -fsSL https://bun.sh/install | bash88```89902. Clone and install:91```bash92git clone https://github.com/vespo92/OPNSenseMCP.git93cd OPNSenseMCP94bun install95```96973. Create your `.env` file (same as npm version above)98994. Run with Bun:100```bash101# Development with hot reload102bun run dev:bun103104# Production105bun run start:bun106```107108### Using Bun with Claude Desktop109110```json111{112 "mcpServers": {113 "opnsense": {114 "command": "bun",115 "args": ["run", "/path/to/OPNSenseMCP/src/index.ts"],116 "env": {117 "OPNSENSE_HOST": "https://your-opnsense:port",118 "OPNSENSE_API_KEY": "your-key",119 "OPNSENSE_API_SECRET": "your-secret",120 "OPNSENSE_VERIFY_SSL": "false"121 }122 }123 }124}125```126127## Usage with Claude Desktop (npm)128129Add to your Claude Desktop configuration (`claude_desktop_config.json`):130131```json132{133 "mcpServers": {134 "opnsense": {135 "command": "npx",136 "args": ["opnsense-mcp-server"],137 "env": {138 "OPNSENSE_HOST": "https://your-opnsense:port",139 "OPNSENSE_API_KEY": "your-key",140 "OPNSENSE_API_SECRET": "your-secret",141 "OPNSENSE_VERIFY_SSL": "false"142 }143 }144 }145}146```147148## Common Use Cases149150### Fix DMZ NAT Issues151```javascript152// Automatically fix DMZ to LAN routing153await mcp.call('nat_fix_dmz', {154 dmzNetwork: '10.0.6.0/24',155 lanNetwork: '10.0.0.0/24'156});157```158159### Create Firewall Rules160```javascript161// Allow NFS from DMZ to NAS162await mcp.call('firewall_create_rule', {163 action: 'pass',164 interface: 'opt8',165 source: '10.0.6.0/24',166 destination: '10.0.0.14/32',167 protocol: 'tcp',168 destination_port: '2049',169 description: 'Allow NFS from DMZ'170});171```172173### Diagnose Routing Issues174```javascript175// Run comprehensive routing diagnostics176await mcp.call('routing_diagnostics', {177 sourceNetwork: '10.0.6.0/24',178 destNetwork: '10.0.0.0/24'179});180```181182### Execute CLI Commands183```javascript184// Run any OPNsense CLI command185await mcp.call('system_execute_command', {186 command: 'pfctl -s state | grep 10.0.6'187});188```189190## MCP Tools Reference191192The server provides 50+ MCP tools organized by category:193194### Firewall Tools195- `firewall_list_rules` - List all firewall rules196- `firewall_create_rule` - Create a new rule197- `firewall_update_rule` - Update existing rule198- `firewall_delete_rule` - Delete a rule199- `firewall_apply_changes` - Apply pending changes200201### NAT Tools202- `nat_list_outbound` - List outbound NAT rules203- `nat_set_mode` - Set NAT mode204- `nat_create_outbound_rule` - Create NAT rule205- `nat_fix_dmz` - Fix DMZ NAT issues206- `nat_analyze_config` - Analyze NAT configuration207208### Network Tools209- `arp_list` - List ARP table entries210- `routing_diagnostics` - Diagnose routing issues211- `routing_fix_all` - Auto-fix routing problems212- `interface_list` - List network interfaces213- `vlan_create` - Create VLAN214215### System Tools216- `system_execute_command` - Execute CLI command217- `backup_create` - Create configuration backup218- `service_restart` - Restart a service219220For a complete list, see [docs/api/mcp-tools.md](docs/api/mcp-tools.md).221222## Documentation223224- [Quick Start Guide](docs/guides/quick-start.md)225- [Configuration Guide](docs/guides/configuration.md)226- [NAT Management](docs/features/nat.md)227- [SSH/CLI Execution](docs/features/ssh.md)228- [Firewall Rules](docs/features/firewall.md)229- [Troubleshooting](docs/guides/troubleshooting.md)230231## Testing232233The repository includes comprehensive testing utilities:234235```bash236# Test NAT functionality237npx tsx scripts/test/test-nat-ssh.ts238239# Test firewall rules240npx tsx scripts/test/test-rules.ts241242# Test routing diagnostics243npx tsx scripts/test/test-routing.ts244245# Run all tests246npm test247```248249## Development250251### Building from Source252```bash253git clone https://github.com/vespo92/OPNSenseMCP.git254cd OPNSenseMCP255npm install256npm run build257```258259### Project Structure260```261OPNSenseMCP/262├── src/ # Source code263│ ├── api/ # API client264│ ├── resources/ # Resource implementations265│ └── index.ts # MCP server entry266├── docs/ # Documentation267├── scripts/ # Utility scripts268│ ├── test/ # Test scripts269│ ├── debug/ # Debug utilities270│ └── fixes/ # Fix scripts271└── dist/ # Build output272```273274## Troubleshooting275276### API Authentication Failed277- Verify API key and secret are correct278- Ensure API access is enabled in OPNsense279- Check firewall rules allow API access280281### SSH Connection Failed282- Verify SSH credentials in `.env`283- Ensure SSH is enabled on OPNsense284- Check user has appropriate privileges285286### NAT Features Not Working287- NAT management requires SSH access288- Add SSH credentials to environment variables289- Test with: `npx tsx scripts/test/test-nat-ssh.ts`290291## Contributing292293Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.294295## License296297This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.298299## Support300301- **Issues**: [GitHub Issues](https://github.com/vespo92/OPNSenseMCP/issues)302- **Discussions**: [GitHub Discussions](https://github.com/vespo92/OPNSenseMCP/discussions)303- **Documentation**: [Full Documentation](docs/)304305## Acknowledgments306307- Built for use with [Anthropic's Claude](https://claude.ai)308- Implements the [Model Context Protocol](https://modelcontextprotocol.io)309- Designed for [OPNsense](https://opnsense.org) firewall310311---312313**Version**: 0.8.2 | **Status**: Production Ready | **Last Updated**: August 2025314
Full transparency — inspect the skill content before installing.