OPNSense

You can run and control an MCP server that connects to your OPNsense firewall to manage rules, NAT, diagnostics, and CLI tasks from any MCP client. This server exposes powerful capabilities for automated firewall administration, configuration backups, and infrastructure as code, making complex operations repeatable and auditable.

How to use

You use an MCP client to call predefined tools that interact with your OPNsense firewall. Common workflows include creating and updating firewall rules, fixing NAT or routing issues, performing diagnostics, and executing trusted CLI commands. Start by starting the MCP server on a host that can reach your OPNsense device, then configure your MCP client to connect to that server. Once connected, you can orchestrate multiple tasks in sequence, automate routine maintenance, and integrate firewall actions into larger automation flows.

How to install

Prerequisites: you need Node.js 18 or newer and npm installed on the machine that will run the MCP server.

Install the MCP server package globally.

How to install

Prerequisites: you need Node.js 18 or newer and npm installed on the machine that will run the MCP server.

How to install

Install the package globally.

How to install

Create a configuration file with your credentials and options.

How to install

# Step 1: Install the MCP server globally
npm install -g opnsense-mcp-server

# Step 2: Create a configuration file with your credentials
# Example content for .env
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 an SSH key
# OPNSENSE_SSH_KEY_PATH=~/.ssh/id_rsa

How to install

Step 3: Start the MCP server.

How to install

opnsense-mcp-server

Additional content

You can also run the server via a client configuration that launches it as a subprocess. For example, you can use an MCP client to start the server with a specific command and environment.

Security and best practices

Limit API access to trusted clients, use SSL verification in production, and store API keys and SSH credentials securely. Regularly rotate credentials and review access controls. When enabling SSH-based features, ensure SSH access is restricted to administrators and monitor login activity.

Troubleshooting

If you encounter authentication or connectivity issues, verify the host URL, API key and secret, and SSL verification setting. Ensure firewall rules permit API access and that the OPNsense device is reachable from the MCP server host. For SSH features, confirm SSH is enabled on OPNsense and that the credentials have the required privileges.

Testing and validation

Run targeted tests to verify NAT, firewall, and routing tools behave as expected. Use the provided test scripts or your MCP client to confirm connectivity and correct tool responses before deploying in production.

Notes on usage with MCP clients

Configure your MCP client to reference the opnsense MCP server and supply credentials via environment variables or a secure secret store. Structure calls to use tool names such as firewall_create_rule, nat_fix_dmz, routing_diagnostics, and system_execute_command for common tasks.

Available tools

firewall_list_rules

List all firewall rules currently configured on the OPNsense firewall.

firewall_create_rule

Create a new firewall rule with specified action, interface, source, destination, protocol, and ports.

firewall_update_rule

Update an existing firewall rule by its identifier.

firewall_delete_rule

Delete a firewall rule by its identifier.

firewall_apply_changes

Apply pending firewall configuration changes.

nat_list_outbound

List outbound NAT rules.

nat_set_mode

Set NAT mode to automatic, hybrid, manual, or disabled.

nat_create_outbound_rule

Create a NAT outbound rule.

nat_fix_dmz

Automatically fix DMZ NAT routing issues between DMZ and LAN.

nat_analyze_config

Analyze current NAT configuration for issues.

arp_list

List ARP table entries with vendor identification.

routing_diagnostics

Run comprehensive routing diagnostics between networks.

routing_fix_all

Auto-fix common routing problems.

interface_list

List network interfaces and configurations.

vlan_create

Create a VLAN on a specified interface.

system_execute_command

Execute a CLI command on the OPNsense system.

backup_create

Create a configuration backup.

service_restart

Restart a service on OPNsense.