Labsco
Pixelworlds logo

OPNsense MCP Server

★ 59

from Pixelworlds

A comprehensive MCP server for managing OPNsense firewalls, offering over 300 tools for configuration and monitoring.

🔥🔥🔥🔥✓ VerifiedAccount requiredAdvanced setup
#git

OPNsense MCP Server

A modular Model Context Protocol (MCP) server that provides 88 module-based tools giving access to over 2000 OPNsense firewall management methods through a type-safe TypeScript interface.

Features

  • Modular Architecture - 88 logical tools (one per module) instead of 2000+ individual tools
  • Complete API Coverage - Access to 752 core methods and 1271 plugin methods
  • Type-Safe - Full TypeScript support with @richard-stovall/opnsense-typescript-client v0.5.3
  • Plugin Support - Optional support for 64 plugin modules
  • Smart Organization - Related operations grouped by module for easier discovery

The MCP server acts as a bridge between AI assistants (like Claude Desktop) and your OPNsense firewall, providing secure API access through a modular tool interface.

<small>Usage in Claude Desktop</small> OPNsense MCP Server Network Architecture

<small>Usage in Claude Code</small> <img width="920" alt="image" src="https://github.com/user-attachments/assets/7833e6c6-45e3-4c98-a234-46a0da8c362d" />

How It Works

The modular MCP server provides your AI assistant with 88 module-based tools. Each tool represents an OPNsense module and accepts a method parameter to specify the operation.

Tool Usage Pattern:

Copy & paste — that's it
{
  "tool": "firewall_manage",
  "arguments": {
    "method": "aliasSearchItem",
    "params": {
      "searchPhrase": "web"
    }
  }
}

Example prompts:

  • "Use core_manage to check system status"
  • "Use firewall_manage to list all firewall aliases"
  • "Use interfaces_manage to get network interface information"
  • "Use plugin_nginx_manage to check the web server configuration"
  • "Use diagnostics_manage to view the ARP table"

The modular approach makes it easy to discover related functionality - all firewall operations are in firewall_manage, all VPN operations in their respective modules (openvpn_manage, ipsec_manage, wireguard_manage).

Available Module Tools

Core Modules (24 tools)

Each tool provides access to all methods within that module:

Tool NameDescriptionExample Methods
core_manageCore system functionsbackupBackups, systemReboot, firmwareInfo
firewall_manageFirewall rules & aliasesaliasSearchItem, filterAddRule, natSearchRule
interfaces_manageNetwork interfacesgetInterfaces, vlanAddItem, setInterface
diagnostics_manageSystem diagnosticsinterfaceGetArp, systemActivityGetActivity
auth_manageAuthenticationuserSearchUser, groupSearchGroup
firmware_manageFirmware updatescheck, update, upgrade, changelog
openvpn_manageOpenVPNinstancesSearch, instancesAdd, serviceReconfigure
ipsec_manageIPsec VPNtunnelSearchPhase1, connectionStatus
wireguard_manageWireGuard VPNserverSearchServer, clientSearchClient
unbound_manageDNS resolverhostOverrideSearchItem, serviceReconfigure
dhcpv4_manageDHCP serversearchLease, addReservation

Plugin Modules (64 tools when enabled)

Popular plugin modules:

Tool NameDescriptionExample Methods
plugin_nginx_manageNginx web servergeneralGet, upstreamSearchUpstream
plugin_haproxy_manageHAProxy load balancerserverSearchServer, statsGet
plugin_caddy_manageCaddy web serverreverseProxySearchDomain, serviceStatus
plugin_bind_manageBIND DNSdomainSearchDomain, recordSearchRecord
plugin_acmeclient_manageLet's EncryptcertificatesSearch, certificatesIssue

Building from Source

If you want to contribute or customize the server:

Copy & paste — that's it
# Clone the repository
git clone https://github.com/richard-stovall/opnsense-mcp-server.git
cd opnsense-mcp-server

# Install dependencies with Yarn 4.9.2
yarn install

# Build the project
yarn build

# Run locally
yarn start

Development

Development Scripts

Copy & paste — that's it
yarn generate-tools  # Generate tool definitions
yarn build          # Build the server
yarn build:all      # Generate tools and build
yarn dev            # Run with hot reload
yarn type-check     # Type check without emitting
yarn start          # Start the server

Technology Stack

  • Runtime: Node.js with tsx for TypeScript execution
  • Package Manager: Yarn 4.9.2 with Plug'n'Play
  • Build System: Simple TypeScript compilation to single file
  • Language: TypeScript 5.3+
  • MCP SDK: @modelcontextprotocol/sdk
  • API Client: @richard-stovall/opnsense-typescript-client
  • Validation: Zod for schema validation
  • Testing: Jest with TypeScript support

API Integration

The server uses the @richard-stovall/opnsense-typescript-client package which provides:

  • Complete type safety for all API calls
  • Built-in error handling and retries
  • Support for all 601 OPNsense API endpoints
  • Modern Fetch API based implementation

Example Tool Implementation

Copy & paste — that's it
const response = await client.system.getStatus();
return {
  content: [
    {
      type: 'text',
      text: JSON.stringify(response.data, null, 2),
    },
  ],
};

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

License

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

Acknowledgments

Made with love for the OPNsense community