MCPs
OPNsense MCP Server

OPNsense MCP Server

AI-powered firewall and network management for OPNsense

Stars

Forks

Watchers

Issues

OPNsense MCP Server provides a comprehensive Model Context Protocol server for automating and managing OPNsense firewall configurations. It enables AI assistants, such as Claude, to directly interact with and control networking features including firewall rules, NAT, VLANs, diagnostics, and advanced system operations via API and SSH. The tool supports batch operations, direct command execution, and advanced troubleshooting, enhancing network management automation. It also supports integration for infrastructure as code and toolchains supporting MCP environments.

Key Features

Complete firewall CRUD operations

SSH-based NAT and system management

Comprehensive network diagnostics

Batch rule creation and control

VLAN and interface management

Direct execution of OPNsense CLI commands

Configuration backup and restore

DHCP and DNS blocklist tools

HAProxy and load balancer support

Automated troubleshooting and auto-fix

Use Cases

Automating OPNsense firewall rule management

Diagnosing and auto-fixing network connectivity issues

Managing NAT rules, modes, and exceptions

Executing system-level operations via SSH on OPNsense

Batch creation and update of network rules for large environments

Integration with AI assistants for real-time network management

Backing up and restoring OPNsense configurations

Building infrastructure as code for network appliances

Managing VLANs and inter-VLAN routing

Viewing and managing DHCP leases and DNS blocklists

README

OPNsense MCP Server

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.

Features

🔥 Firewall Management

Complete CRUD operations for firewall rules
Proper handling of API-created "automation rules"
Inter-VLAN routing configuration
Batch rule creation and management
Enhanced persistence with multiple fallback methods

🌐 NAT Configuration (SSH-based)

Outbound NAT rule management
NAT mode control (automatic/hybrid/manual/disabled)
No-NAT exception rules for inter-VLAN traffic
Automated DMZ NAT issue resolution
Direct XML configuration manipulation

🔍 Network Diagnostics

Comprehensive routing analysis
ARP table inspection with vendor identification
Interface configuration management
Network connectivity troubleshooting
Auto-fix capabilities for common issues

🖥️ SSH/CLI Execution

Direct command execution on OPNsense
Configuration file manipulation
System-level operations not available via API
Service management and restarts

📊 Additional Capabilities

VLAN management
DHCP lease viewing and management
DNS blocklist configuration
HAProxy load balancer support
Configuration backup and restore
Infrastructure as Code support

Installation

Prerequisites

Node.js 18+ and npm
OPNsense firewall (v24.7+ recommended)
API credentials for OPNsense
SSH access (optional, for advanced features)

Quick Start

Install the package:

bash

npm install -g opnsense-mcp-server

Create a .env file with your credentials:

bash

# Required
OPNSENSE_HOST=https://your-opnsense-host:port
OPNSENSE_API_KEY=your-api-key
OPNSENSE_API_SECRET=your-api-secret
OPNSENSE_VERIFY_SSL=false

# Optional - for SSH features
OPNSENSE_SSH_HOST=your-opnsense-host
OPNSENSE_SSH_USERNAME=root
OPNSENSE_SSH_PASSWORD=your-password
# Or use SSH key
# OPNSENSE_SSH_KEY_PATH=~/.ssh/id_rsa

Start the MCP server:

bash

opnsense-mcp-server

Usage with Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

json

{
  "mcpServers": {
    "opnsense": {
      "command": "npx",
      "args": ["opnsense-mcp-server"],
      "env": {
        "OPNSENSE_HOST": "https://your-opnsense:port",
        "OPNSENSE_API_KEY": "your-key",
        "OPNSENSE_API_SECRET": "your-secret",
        "OPNSENSE_VERIFY_SSL": "false"
      }
    }
  }
}

Common Use Cases

Fix DMZ NAT Issues

javascript

// Automatically fix DMZ to LAN routing
await mcp.call('nat_fix_dmz', {
  dmzNetwork: '10.0.6.0/24',
  lanNetwork: '10.0.0.0/24'
});

Create Firewall Rules

javascript

// Allow NFS from DMZ to NAS
await mcp.call('firewall_create_rule', {
  action: 'pass',
  interface: 'opt8',
  source: '10.0.6.0/24',
  destination: '10.0.0.14/32',
  protocol: 'tcp',
  destination_port: '2049',
  description: 'Allow NFS from DMZ'
});

Diagnose Routing Issues

javascript

// Run comprehensive routing diagnostics
await mcp.call('routing_diagnostics', {
  sourceNetwork: '10.0.6.0/24',
  destNetwork: '10.0.0.0/24'
});

Execute CLI Commands

javascript

// Run any OPNsense CLI command
await mcp.call('system_execute_command', {
  command: 'pfctl -s state | grep 10.0.6'
});

MCP Tools Reference

The server provides 50+ MCP tools organized by category:

Firewall Tools

firewall_list_rules - List all firewall rules
firewall_create_rule - Create a new rule
firewall_update_rule - Update existing rule
firewall_delete_rule - Delete a rule
firewall_apply_changes - Apply pending changes

NAT Tools

nat_list_outbound - List outbound NAT rules
nat_set_mode - Set NAT mode
nat_create_outbound_rule - Create NAT rule
nat_fix_dmz - Fix DMZ NAT issues
nat_analyze_config - Analyze NAT configuration

Network Tools

arp_list - List ARP table entries
routing_diagnostics - Diagnose routing issues
routing_fix_all - Auto-fix routing problems
interface_list - List network interfaces
vlan_create - Create VLAN

System Tools

system_execute_command - Execute CLI command
backup_create - Create configuration backup
service_restart - Restart a service

For a complete list, see docs/api/mcp-tools.md.

Documentation

Testing

The repository includes comprehensive testing utilities:

bash

# Test NAT functionality
npx tsx scripts/test/test-nat-ssh.ts

# Test firewall rules
npx tsx scripts/test/test-rules.ts

# Test routing diagnostics
npx tsx scripts/test/test-routing.ts

# Run all tests
npm test

Development

Building from Source

bash

git clone https://github.com/vespo92/OPNSenseMCP.git
cd OPNSenseMCP
npm install
npm run build

Project Structure

OPNSenseMCP/
├── src/                 # Source code
│   ├── api/            # API client
│   ├── resources/      # Resource implementations
│   └── index.ts        # MCP server entry
├── docs/               # Documentation
├── scripts/            # Utility scripts
│   ├── test/          # Test scripts
│   ├── debug/         # Debug utilities
│   └── fixes/         # Fix scripts
└── dist/               # Build output

Troubleshooting

API Authentication Failed

Verify API key and secret are correct
Ensure API access is enabled in OPNsense
Check firewall rules allow API access

SSH Connection Failed

Verify SSH credentials in .env
Ensure SSH is enabled on OPNsense
Check user has appropriate privileges

NAT Features Not Working

NAT management requires SSH access
Add SSH credentials to environment variables
Test with: npx tsx scripts/test/test-nat-ssh.ts

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: Full Documentation

Acknowledgments

Built for use with Anthropic's Claude
Implements the Model Context Protocol
Designed for OPNsense firewall

Version: 0.8.2 | Status: Production Ready | Last Updated: August 2025

Star History

Repository Owner

vespo92

User

Repository Details

Language TypeScript

Default Branch main

Size 1,121 KB

Contributors 2

License MIT License

MCP Verified Nov 12, 2025

Programming Languages

TypeScript

69.87%

JavaScript

23.91%

PLpgSQL

2.6%

Batchfile

1.98%

HTML

1.22%

Powershell

0.28%

Dockerfile

0.14%

Join Our Newsletter

Stay updated with the latest AI tools, news, and offers by subscribing to our weekly newsletter.

Related MCPs

Discover similar Model Context Protocol servers

Model Context Protocol Server for Home Assistant

Seamlessly connect Home Assistant to LLMs for natural language smart home control via MCP.

Enables integration between a local Home Assistant instance and language models using the Model Context Protocol (MCP). Facilitates natural language monitoring and control of smart home devices, with robust API support for state management, automation, real-time updates, and system administration. Features secure, token-based access, and supports mobile and HTTP clients. Designed to bridge Home Assistant environments with modern AI-driven automation.

⭐ 468
MCP
tevonsb/homeassistant-mcp

MCP Server for Odoo

Connect AI assistants to Odoo ERP systems using the Model Context Protocol.

MCP Server for Odoo enables AI assistants such as Claude to interact seamlessly with Odoo ERP systems via the Model Context Protocol (MCP). It provides endpoints for searching, creating, updating, and deleting Odoo records using natural language while respecting access controls and security. The server supports integration with any Odoo instance, includes smart features like pagination and LLM-optimized output, and offers both demo and production-ready modes.

⭐ 101
MCP
ivnvxd/mcp-server-odoo

Weblate MCP Server

Seamlessly connect AI assistants to Weblate for translation management via the Model Context Protocol.

Weblate MCP Server enables AI assistants and clients to directly manage Weblate translation projects through the Model Context Protocol (MCP). It integrates with the Weblate REST API, allowing natural language interaction for project and translation management. The tool offers multiple transport options including HTTP, SSE, and STDIO, and is optimized for large language model workflows. Full support for project, component, and translation operations is provided, with a focus on type safety and flexible environment configuration.

⭐ 9
MCP
mmntm/weblate-mcp

Offorte MCP Server

Bridge AI agents with Offorte proposal automation via the Model Context Protocol.

Offorte MCP Server enables external AI models to create and send proposals through Offorte by implementing the Model Context Protocol. It facilitates automation workflows between AI agents and Offorte's proposal engine, supporting seamless integration with chat interfaces and autonomous systems. The server provides a suite of tools for managing contacts, proposals, templates, and automation sets, streamlining the proposal creation and delivery process via standardized context handling. Designed for extensibility and real-world automation, it leverages Offorte's public API to empower intelligent business proposals.

⭐ 4
MCP
offorte/offorte-mcp-server

GitHub MCP Server

Connect AI tools directly to GitHub for repository, issue, and workflow management via natural language.

GitHub MCP Server enables AI tools such as agents, assistants, and chatbots to interact natively with the GitHub platform. It allows these tools to access repositories, analyze code, manage issues and pull requests, and automate workflows using the Model Context Protocol (MCP). The server supports integration with multiple hosts, including VS Code and other popular IDEs, and can operate both remotely and locally. Built for developers seeking to enhance AI-powered development workflows through seamless GitHub context access.

⭐ 24,418
MCP
github/github-mcp-server

Azure DevOps MCP Server

Standardized AI access to Azure DevOps via Model Context Protocol.

Implements the Model Context Protocol (MCP) to enable AI assistants to securely and efficiently interact with Azure DevOps resources. Provides a standardized bridge for managing projects, work items, repositories, pull requests, and pipelines through natural language interfaces. Supports modular authentication and a feature-based architecture for scalability and integration. Facilitates seamless integration with AI tools such as Claude Desktop and Cursor AI.

⭐ 306
MCP
Tiberriver256/mcp-server-azure-devops

View all Alternatives

Didn't find tool you were looking for?

Search AI Tools

OPNsense MCP Server

Key Features

Use Cases

README

OPNsense MCP Server

Features

🔥 Firewall Management

🌐 NAT Configuration (SSH-based)

🔍 Network Diagnostics

🖥️ SSH/CLI Execution

📊 Additional Capabilities

Installation

Prerequisites

Quick Start

Usage with Claude Desktop

Common Use Cases

Fix DMZ NAT Issues

Create Firewall Rules

Diagnose Routing Issues

Execute CLI Commands

MCP Tools Reference

Firewall Tools

NAT Tools

Network Tools

System Tools

Documentation

Testing

Development

Building from Source

Project Structure

Troubleshooting

API Authentication Failed

SSH Connection Failed

NAT Features Not Working

Contributing

License

Support

Acknowledgments

Star History

Repository Owner

Repository Details

Programming Languages

Related MCPs