OPNsense MCP Server

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

- 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-clientv0.5.3
- Plugin Support- Optional support for 64 plugin modules
- Smart Organization- Related operations grouped by module for easier discovery

npm install -g @richard-stovall/opnsense-mcp-server

{ "mcpServers": { "opnsense": { "command": "npx", "args": ["-y", "@richard-stovall/opnsense-mcp-server"], "env": { "OPNSENSE_URL": "https://192.168.1.1", "OPNSENSE_API_KEY": "your-api-key", "OPNSENSE_API_SECRET": "your-api-secret", "OPNSENSE_VERIFY_SSL": "false" } } } }

{ "mcpServers": { "opnsense": { "command": "node", "args": [ "/path/to/opnsense-mcp-server/index.js", "--url", "https://YOUR-OPNSENSE-IP", "--api-key", "YOUR-API-KEY", "--api-secret", "YOUR-API-SECRET", "--no-verify-ssl" ] } } }

Enable Plugin Tools:To include all 64 plugin module tools, add"--plugins"to the args or set"INCLUDE_PLUGINS": "true"in env.

Once configured, you can test the connection by asking Claude:

- "What MCP tools are available?"
- "Use core_manage to get the system status"
- "Use firewall_manage to search for all aliases"
- "Use interfaces_manage to list all network interfaces"
- Verify your OPNsense API is enabled
- Check that the API key has appropriate permissions
- Ensure the IP/hostname is accessible from your machine
- For self-signed certificates, use--no-verify-sslor set"OPNSENSE_VERIFY_SSL": "false"

View Server Logs:Check Claude Desktop logs for any error messages from the MCP server.

Test Manually:You can test the server manually before using with Claude Desktop:

node /path/to/opnsense-mcp-server/index.js \ --url https://YOUR-OPNSENSE-IP \ --api-key YOUR-API-KEY \ --api-secret YOUR-API-SECRET \ --no-verify-ssl

OPNsense MCP server v0.6.0 (modular) started Core tools: 24 modules Plugin tools: 64 modules (disabled) Total available: 24 modules

Add to your Cursor settings (.cursor/mcp.jsonin your project or~/.cursor/mcp.jsonglobally):

{ "mcpServers": { "opnsense": { "command": "npx", "args": ["-y", "@richard-stovall/opnsense-mcp-server"], "env": { "OPNSENSE_URL": "https://192.168.1.1", "OPNSENSE_API_KEY": "your-api-key", "OPNSENSE_API_SECRET": "your-api-secret", "OPNSENSE_VERIFY_SSL": "false" } } } }

The server accepts configuration through environment variables:

- OPNSENSE_URL- OPNsense host URL (required)
- OPNSENSE_API_KEY- API key for authentication (required)
- OPNSENSE_API_SECRET- API secret for authentication (required)
- INCLUDE_PLUGINS- Set to "true" to enable 64 plugin module tools (optional)
- OPNSENSE_VERIFY_SSL- Set to "false" to disable SSL verification (development only)

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

{ "tool": "firewall_manage", "arguments": { "method": "aliasSearchItem", "params": { "searchPhrase": "web" } } }

- "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 infirewall_manage, all VPN operations in their respective modules (openvpn_manage,ipsec_manage,wireguard_manage).

Each tool provides access to all methods within that module:

If you want to contribute or customize the server:

# 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

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

- 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

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

const response = await client.system.getStatus(); return { content: [ { type: 'text', text: JSON.stringify(response.data, null, 2), }, ], };

Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (git checkout -b feature/AmazingFeature)
- Commit your changes (git commit -m 'Add some AmazingFeature')
- Push to the branch (git push origin feature/AmazingFeature)
- Open a Pull Request

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

- Built on theModel Context Protocolby Anthropic
- Powered by@richard-stovall/opnsense-typescript-client
- Inspired by the OPNsense community

A server for real-time network packet monitoring and security analysis.