OPNSenseMCP

Purpose

OPNSenseMCP is a Model Context Protocol (MCP) server for the OPNsense open-source firewall, positioned as an Infrastructure as Code (IaC) agent. Its core purpose is to let AI assistants such as Claude directly manage an OPNsense firewall through natural language, completing configuration changes, network diagnostics, and automation tasks, reducing the cost of manual operations and command-line interaction.

Main Capabilities

• Firewall management: full CRUD operations for firewall rules, correct handling of "automation rules" created via the API, inter-VLAN routing configuration, bulk rule creation and management, enhanced persistence through 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, automatic repair of DMZ NAT issues, direct XML configuration operations.
• Network diagnostics: comprehensive routing analysis, ARP table inspection with vendor identification, interface configuration management, network connectivity troubleshooting, automatic repair of common issues.
• SSH/CLI execution: directly execute commands on OPNsense, configuration file operations, system-level operations unavailable via the API, service management and restart.
• Additional capabilities: VLAN management, DHCP lease viewing and management, DNS blocklist configuration, HAProxy load balancing support, configuration backup and restore, Infrastructure as Code support.

Usage

Runtime requirements are Node.js 18+ (Bun 1.1.39+ for development), an OPNsense firewall (v24.7+ recommended), API credentials, and SSH access as optional (for advanced features).

Quick start via npm: install the package, create a .env file containing credentials, start the MCP server. Bun can also be used for faster startup and better performance: install Bun, clone and install, create a .env file.

When using the npm version in Claude Desktop, the server configuration must be added to claude_desktop_config.json.

Safety Modes

By default, this server can make live, immediate changes to the firewall, including adding and deleting rules, changing NAT, restarting services, and running whitelisted shell commands via SSH. The server provides two operator-onlyenvironment variables set as a safety net; tool calls cannot set or override them; both are enforced uniformly at the two underlying nodes, the API client and the SSH executor, covering all 140+ tools. If both are set, OPNSENSE_READ_ONLY takes priority. For specific configuration, refer to CONFIGURATION.md; for how it works, refer to docs/features/safety-modes.md.

MCP Tools

The server provides 50+ MCP tools organized by category, for example: firewall_list_rules, firewall_create_rule, firewall_update_rule, firewall_delete_rule, firewall_apply_changes, nat_list_outbound, nat_set_mode, nat_create_outbound_rule, nat_fix_dmz, nat_analyze_config, arp_list, routing_diagnostics, routing_fix_all, interface_list, vlan_create, system_execute_command, backup_create, service_restart. See docs/api/mcp-tools.md for the complete list.

Build and Project Structure

The project uses Bun as its toolchain for development, but the published package is still plain Node, used via node dist/index.js, so Bun is only used when participating in project development. The lockfile is bun.lock, there is no package-lock.json, and CI runs bun install --frozen-lockfile, so when package.json changes, bun.lock must be committed along with it.

Common Troubleshooting

• API authentication failure: verify that the API key and secret are correct; ensure API access is enabled in OPNsense; check that firewall rules allow API access.
• SSH connection failure: verify the SSH credentials in .env; ensure SSH is enabled on OPNsense; check whether the user has appropriate permissions.
• NAT features not working: NAT management requires SSH access; add SSH credentials to the environment variables; you can test with npx tsx scripts/test/test-nat-ssh.ts.

Limitations and Status

NAT configuration and related features depend on SSH access; some system-level operations cannot be completed through the API. The project uses the MIT license, version 0.8.2, is production-ready, and was last updated in August 2025. Detailed documentation, quick start, configuration guide, SSH/CLI execution instructions, troubleshooting, and the full API reference can be found in the repository documentation.