Which integrations are available for this server?

Supports Cloudflare integration for DNS-01 ACME challenges to facilitate automated certificate validation and renewal within the OPNsense environment. Manages Let's Encrypt ACME accounts and certificates through the OPNsense ACME client, providing tools for registration, automated renewal, and status tracking. Enables comprehensive management of OPNsense firewall infrastructure via its REST API, including tools for firewall rules, DNS overrides, DHCP mappings, system diagnostics, configuration backups, and service control.

mcp-opnsense

GitHub release License: AGPL-3.0 CalVer Node.js MCP Tools TypeScript

Slim OPNsense MCP Server for managing firewall infrastructure via the OPNsense REST API.

No SSH. No shell execution. API-only. 3 runtime dependencies.

Features

62 tools across 8 domains:

DNS/Unbound (12) — Host overrides, forwards, blocklist, cache management
Firewall (8) — Rules, aliases, NAT, apply changes
Diagnostics (8) — ARP, routes, ping, traceroute, DNS lookup, firewall states/logs
Interfaces (3) — List, configuration, statistics (read-only)
DHCP (5) — Leases, static mappings (ISC DHCPv4 + Kea dual support)
System (7) — Info, backup (list/download/revert), certificate listing, service control
ACME/Let's Encrypt (14) — Accounts, challenges, certificates, renewal, settings
Firmware/Plugins (5) — Version info, plugin management

Quick Start

npm install
cp .env.example .env   # Edit with your OPNsense API credentials
npm run build
node dist/index.js     # stdio transport for MCP

Claude Code Integration

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "opnsense": {
      "command": "node",
      "args": ["/path/to/mcp-opnsense/dist/index.js"],
      "env": {
        "OPNSENSE_URL": "https://your-opnsense.example.com",
        "OPNSENSE_API_KEY": "your-api-key",
        "OPNSENSE_API_SECRET": "your-api-secret",
        "OPNSENSE_VERIFY_SSL": "true"
      }
    }
  }
}

Environment Variables

Variable	Required	Default	Description
`OPNSENSE_URL`	Yes	—	OPNsense base URL (e.g. `https://192.168.1.1`)
`OPNSENSE_API_KEY`	Yes	—	API key for authentication
`OPNSENSE_API_SECRET`	Yes	—	API secret for authentication
`OPNSENSE_VERIFY_SSL`	No	`true`	Set to `false` for self-signed certificates
`OPNSENSE_TIMEOUT`	No	`30000`	Request timeout in milliseconds

Available Tools (62)

DNS/Unbound (12 tools)

Tool	Description
`opnsense_dns_list_overrides`	List host overrides (A/AAAA/CNAME)
`opnsense_dns_add_override`	Add a host override record
`opnsense_dns_delete_override`	Delete a host override by UUID
`opnsense_dns_list_forwards`	List DNS-over-TLS forwarding servers
`opnsense_dns_add_forward`	Add a DNS forwarding server
`opnsense_dns_delete_forward`	Delete a DNS forward by UUID
`opnsense_dns_list_blocklist`	List domain overrides (blocked domains)
`opnsense_dns_block_domain`	Block a domain
`opnsense_dns_unblock_domain`	Unblock a domain by UUID
`opnsense_dns_flush_cache`	Flush DNS cache and DNSBL data
`opnsense_dns_diagnostics`	Dump DNS cache for diagnostics
`opnsense_dns_apply`	Apply DNS changes (reconfigure Unbound)

Firewall (8 tools)

Tool	Description
`opnsense_fw_list_rules`	List all firewall filter rules
`opnsense_fw_add_rule`	Create a firewall rule
`opnsense_fw_update_rule`	Update a firewall rule by UUID
`opnsense_fw_delete_rule`	Delete a firewall rule by UUID
`opnsense_fw_toggle_rule`	Enable/disable a firewall rule
`opnsense_fw_list_aliases`	List firewall aliases (host, network, port, URL)
`opnsense_fw_manage_alias`	Create/update/delete aliases
`opnsense_fw_apply`	Apply pending firewall changes

Diagnostics (8 tools)

Tool	Description
`opnsense_diag_arp_table`	Show ARP table (IP-to-MAC mappings)
`opnsense_diag_routes`	Show routing table
`opnsense_diag_ping`	Ping a host from OPNsense
`opnsense_diag_traceroute`	Traceroute to a destination
`opnsense_diag_dns_lookup`	Perform DNS lookup from OPNsense
`opnsense_diag_fw_states`	List active firewall connection states
`opnsense_diag_fw_logs`	Retrieve recent firewall log entries
`opnsense_diag_system_info`	Get system status (CPU, memory, uptime, disk)

Interfaces (3 tools, read-only)

Tool	Description
`opnsense_if_list`	List all network interfaces with device mappings
`opnsense_if_get`	Get detailed interface configuration
`opnsense_if_stats`	Get traffic statistics for all interfaces

DHCP (5 tools)

Tool	Description
`opnsense_dhcp_list_leases`	List all current DHCPv4 leases
`opnsense_dhcp_find_lease`	Search leases by IP, MAC, or hostname
`opnsense_dhcp_list_static`	List static DHCP mappings (reservations)
`opnsense_dhcp_add_static`	Add a static DHCP mapping
`opnsense_dhcp_delete_static`	Delete a static mapping by UUID

System (7 tools)

Tool	Description
`opnsense_sys_info`	Get system status (hostname, versions, CPU, memory, uptime, disk)
`opnsense_sys_backup_list`	List all configuration backups with timestamps and descriptions
`opnsense_sys_backup_download`	Download configuration backup as XML (current or specific)
`opnsense_sys_backup_revert`	Revert to a previous configuration backup (destructive)
`opnsense_sys_list_certs`	List all certificates in the trust store
`opnsense_svc_list`	List all services and their running status
`opnsense_svc_control`	Start, stop, or restart a service by name

ACME/Let's Encrypt (14 tools)

Tool	Description
`opnsense_acme_list_accounts`	List ACME accounts (Let's Encrypt, ZeroSSL, etc.)
`opnsense_acme_add_account`	Register a new ACME account with a CA
`opnsense_acme_delete_account`	Delete an ACME account by UUID
`opnsense_acme_register_account`	Trigger registration of an ACME account with its CA
`opnsense_acme_list_challenges`	List all challenge/validation methods
`opnsense_acme_add_challenge`	Add a DNS-01 challenge (Cloudflare, AWS, etc.)
`opnsense_acme_update_challenge`	Update an existing challenge configuration
`opnsense_acme_delete_challenge`	Delete a challenge by UUID
`opnsense_acme_list_certs`	List all ACME certificates and their status
`opnsense_acme_create_cert`	Create a new certificate request
`opnsense_acme_delete_cert`	Delete an ACME certificate by UUID
`opnsense_acme_renew_cert`	Trigger immediate certificate renewal
`opnsense_acme_settings`	Get or update ACME service settings
`opnsense_acme_apply`	Apply pending ACME configuration changes

Firmware/Plugins (5 tools)

Tool	Description
`opnsense_firmware_info`	Get firmware version, architecture, update status
`opnsense_firmware_status`	Check for available firmware upgrades
`opnsense_firmware_list_plugins`	List all available and installed plugins
`opnsense_firmware_install`	Install an OPNsense plugin package
`opnsense_firmware_remove`	Remove a plugin package (requires confirmation)

Skills

Claude Code skills compose MCP tools into higher-level workflows. See .claude/skills/README.md for detailed documentation.

Skill	Slash Command	Description
opnsense-service-health	`/opn-health`	Health dashboard — system status, services, firmware, interfaces
opnsense-acme-renew	`/opn-renew-cert`	ACME certificate status check and renewal
opnsense-backup	`/opn-backup`	Configuration backup management — list, download, revert
opnsense-live-test	`/opn-test`	Live integration test — read + safe writes with cleanup
opnsense-diagnostics	—	Network connectivity diagnostics — ping, traceroute, DNS, ARP
opnsense-dns-management	—	DNS record management — add, delete, apply, verify resolution
opnsense-firewall-audit	—	Firewall security audit — permissive rules, disabled rules, patterns

Known Limitations

Some OPNsense operations are not available via the REST API and require manual GUI access:

Web GUI SSL certificate assignment — ssl-certref can only be changed via System > Settings > Administration in the web UI. See docs/manual-operations.md.
Configuration upload/import — OPNsense has no API to upload configuration XML files. Use opnsense_sys_backup_revert to revert to local backups, or upload via the web GUI.
User/group management — Not exposed via REST API.
VPN configuration — Limited API coverage; most settings require the web UI.

Security

Transport: stdio only — no HTTP endpoints exposed
Authentication: OPNsense API key/secret via environment variables
SSL: Enabled by default, configurable for self-signed certs
No SSH: All operations use the OPNsense REST API exclusively
Input validation: Strict Zod schemas for all tool parameters
Destructive operations: Require explicit confirm: true parameter
See SECURITY.md for the full security policy

Development

npm test          # Run unit tests (vitest)
npm run build     # Compile TypeScript
npx tsc --noEmit  # Type check only

See CONTRIBUTING.md for contribution guidelines.

License

This project is dual-licensed:

Open Source: GNU Affero General Public License v3.0 (AGPL-3.0) — free for open-source and non-commercial use
Commercial: Available for proprietary integrations — see COMMERCIAL_LICENSE.md

If you use mcp-opnsense in a proprietary product or SaaS offering, a commercial license is required. Support development by sponsoring us on GitHub.

Install Server

A

security – no known vulnerabilities

A

license - permissive license

A

quality - confirmed to work

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Report Issue

Related Servers

Looking for Admin?

Admins can modify the Dockerfile, update the server description, and track usage metrics. If you are the server author, to access the admin panel.

Tools

View all tools

mcp-opnsense

mcp-opnsense

Table of Contents

Features

Quick Start

Claude Code Integration

Environment Variables

Available Tools (62)

DNS/Unbound (12 tools)

Firewall (8 tools)

Diagnostics (8 tools)

Interfaces (3 tools, read-only)

DHCP (5 tools)

System (7 tools)

ACME/Let's Encrypt (14 tools)

Firmware/Plugins (5 tools)

Skills

Known Limitations

Security

Development

License

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API