Skip to content
Back to search

opnsense-mcp-server

Modular MCP server for OPNsense firewall management - 88 tools providing access to 2000+ methods through AI assistants

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pixelworlds--opnsense-mcp-server/badge.svg)](/listings/pixelworlds--opnsense-mcp-server)

HTML

<a href="/listings/pixelworlds--opnsense-mcp-server"><img src="/api/listings/pixelworlds--opnsense-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

As an MCP Server

This package is designed to be used as an MCP (Model Context Protocol) server with AI assistants like Claude Desktop, Cursor, or other MCP-compatible clients.

Prerequisites

- Node.js 18 or higher - An OPNsense firewall with API access enabled - API key and secret from your OPNsense installation

Install from npm

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 312 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # OPNsense MCP Server
  2. 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.
  3. ## Features
  4. - **Modular Architecture** - 88 logical tools (one per module) instead of 2000+ individual tools
  5. - **Complete API Coverage** - Access to 752 core methods and 1271 plugin methods
  6. - **Type-Safe** - Full TypeScript support with [@richard-stovall/opnsense-typescript-client](https://www.npmjs.com/package/@richard-stovall/opnsense-typescript-client) v0.5.3
  7. - **Plugin Support** - Optional support for 64 plugin modules
  8. - **Smart Organization** - Related operations grouped by module for easier discovery
  9. 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.
  10. <small>Usage in Claude Desktop</small>
  11. ![OPNsense MCP Server Network Architecture](https://github.com/user-attachments/assets/c7742683-7f25-437a-9747-250f48472a6a)
  12. <small>Usage in Claude Code</small>
  13. <img width="920" alt="image" src="https://github.com/user-attachments/assets/7833e6c6-45e3-4c98-a234-46a0da8c362d" />
  14. ## Installation
  15. ### As an MCP Server
  16. This package is designed to be used as an MCP (Model Context Protocol) server with AI assistants like Claude Desktop, Cursor, or other MCP-compatible clients.
  17. ### Prerequisites
  18. - Node.js 18 or higher
  19. - An OPNsense firewall with API access enabled
  20. - API key and secret from your OPNsense installation
  21. ### Install from npm
  22. ```bash
  23. npm install -g @richard-stovall/opnsense-mcp-server
  24. ```
  25. ## Usage as an MCP Server
  26. ### Claude Desktop Configuration
  27. Add the following to your Claude Desktop configuration file:
  28. **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  29. **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  30. ```json
  31. {
  32. "mcpServers": {
  33. "opnsense": {
  34. "command": "npx",
  35. "args": ["-y", "@richard-stovall/opnsense-mcp-server"],
  36. "env": {
  37. "OPNSENSE_URL": "https://192.168.1.1",
  38. "OPNSENSE_API_KEY": "your-api-key",
  39. "OPNSENSE_API_SECRET": "your-api-secret",
  40. "OPNSENSE_VERIFY_SSL": "false"
  41. }
  42. }
  43. }
  44. }
  45. ```
  46. #### Alternative Configuration Methods
  47. **Using Command Line Arguments:**
  48. ```json
  49. {
  50. "mcpServers": {
  51. "opnsense": {
  52. "command": "node",
  53. "args": [
  54. "/path/to/opnsense-mcp-server/index.js",
  55. "--url",
  56. "https://YOUR-OPNSENSE-IP",
  57. "--api-key",
  58. "YOUR-API-KEY",
  59. "--api-secret",
  60. "YOUR-API-SECRET",
  61. "--no-verify-ssl"
  62. ]
  63. }
  64. }
  65. }
  66. ```
  67. **Enable Plugin Tools:**
  68. To include all 64 plugin module tools, add `"--plugins"` to the args or set `"INCLUDE_PLUGINS": "true"` in env.
  69. #### Testing the Setup
  70. Once configured, you can test the connection by asking Claude:
  71. - "What MCP tools are available?"
  72. - "Use core_manage to get the system status"
  73. - "Use firewall_manage to search for all aliases"
  74. - "Use interfaces_manage to list all network interfaces"
  75. #### Troubleshooting Claude Desktop Setup
  76. **Connection Issues:**
  77. 1. Verify your OPNsense API is enabled
  78. 2. Check that the API key has appropriate permissions
  79. 3. Ensure the IP/hostname is accessible from your machine
  80. 4. For self-signed certificates, use `--no-verify-ssl` or set `"OPNSENSE_VERIFY_SSL": "false"`
  81. **View Server Logs:**
  82. Check Claude Desktop logs for any error messages from the MCP server.
  83. **Test Manually:**
  84. You can test the server manually before using with Claude Desktop:
  85. ```bash
  86. node /path/to/opnsense-mcp-server/index.js \
  87. --url https://YOUR-OPNSENSE-IP \
  88. --api-key YOUR-API-KEY \
  89. --api-secret YOUR-API-SECRET \
  90. --no-verify-ssl
  91. ```
  92. This should output:
  93. ```
  94. OPNsense MCP server v0.6.0 (modular) started
  95. Core tools: 24 modules
  96. Plugin tools: 64 modules (disabled)
  97. Total available: 24 modules
  98. ```
  99. ### Cursor Configuration
  100. Add to your Cursor settings (`.cursor/mcp.json` in your project or `~/.cursor/mcp.json` globally):
  101. ```json
  102. {
  103. "mcpServers": {
  104. "opnsense": {
  105. "command": "npx",
  106. "args": ["-y", "@richard-stovall/opnsense-mcp-server"],
  107. "env": {
  108. "OPNSENSE_URL": "https://192.168.1.1",
  109. "OPNSENSE_API_KEY": "your-api-key",
  110. "OPNSENSE_API_SECRET": "your-api-secret",
  111. "OPNSENSE_VERIFY_SSL": "false"
  112. }
  113. }
  114. }
  115. }
  116. ```
  117. ### Configuration Options
  118. The server accepts configuration through environment variables:
  119. - `OPNSENSE_URL` - OPNsense host URL (required)
  120. - `OPNSENSE_API_KEY` - API key for authentication (required)
  121. - `OPNSENSE_API_SECRET` - API secret for authentication (required)
  122. - `INCLUDE_PLUGINS` - Set to "true" to enable 64 plugin module tools (optional)
  123. - `OPNSENSE_VERIFY_SSL` - Set to "false" to disable SSL verification (development only)
  124. ## How It Works
  125. 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.
  126. **Tool Usage Pattern:**
  127. ```json
  128. {
  129. "tool": "firewall_manage",
  130. "arguments": {
  131. "method": "aliasSearchItem",
  132. "params": {
  133. "searchPhrase": "web"
  134. }
  135. }
  136. }
  137. ```
  138. **Example prompts:**
  139. - "Use core_manage to check system status"
  140. - "Use firewall_manage to list all firewall aliases"
  141. - "Use interfaces_manage to get network interface information"
  142. - "Use plugin_nginx_manage to check the web server configuration"
  143. - "Use diagnostics_manage to view the ARP table"
  144. 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`).
  145. ## Available Module Tools
  146. ### Core Modules (24 tools)
  147. Each tool provides access to all methods within that module:
  148. | Tool Name | Description | Example Methods |
  149. | -------------------- | ------------------------ | ------------------------------------------------------- |
  150. | `core_manage` | Core system functions | `backupBackups`, `systemReboot`, `firmwareInfo` |
  151. | `firewall_manage` | Firewall rules & aliases | `aliasSearchItem`, `filterAddRule`, `natSearchRule` |
  152. | `interfaces_manage` | Network interfaces | `getInterfaces`, `vlanAddItem`, `setInterface` |
  153. | `diagnostics_manage` | System diagnostics | `interfaceGetArp`, `systemActivityGetActivity` |
  154. | `auth_manage` | Authentication | `userSearchUser`, `groupSearchGroup` |
  155. | `firmware_manage` | Firmware updates | `check`, `update`, `upgrade`, `changelog` |
  156. | `openvpn_manage` | OpenVPN | `instancesSearch`, `instancesAdd`, `serviceReconfigure` |
  157. | `ipsec_manage` | IPsec VPN | `tunnelSearchPhase1`, `connectionStatus` |
  158. | `wireguard_manage` | WireGuard VPN | `serverSearchServer`, `clientSearchClient` |
  159. | `unbound_manage` | DNS resolver | `hostOverrideSearchItem`, `serviceReconfigure` |
  160. | `dhcpv4_manage` | DHCP server | `searchLease`, `addReservation` |
  161. ### Plugin Modules (64 tools when enabled)
  162. Popular plugin modules:
  163. | Tool Name | Description | Example Methods |
  164. | -------------------------- | --------------------- | ------------------------------------------- |
  165. | `plugin_nginx_manage` | Nginx web server | `generalGet`, `upstreamSearchUpstream` |
  166. | `plugin_haproxy_manage` | HAProxy load balancer | `serverSearchServer`, `statsGet` |
  167. | `plugin_caddy_manage` | Caddy web server | `reverseProxySearchDomain`, `serviceStatus` |
  168. | `plugin_bind_manage` | BIND DNS | `domainSearchDomain`, `recordSearchRecord` |
  169. | `plugin_acmeclient_manage` | Let's Encrypt | `certificatesSearch`, `certificatesIssue` |
  170. ## Building from Source
  171. If you want to contribute or customize the server:
  172. ```bash
  173. # Clone the repository
  174. git clone https://github.com/richard-stovall/opnsense-mcp-server.git
  175. cd opnsense-mcp-server
  176. # Install dependencies with Yarn 4.9.2
  177. yarn install
  178. # Build the project
  179. yarn build
  180. # Run locally
  181. yarn start
  182. ```
  183. ## Development
  184. ### Development Scripts
  185. ```bash
  186. yarn generate-tools # Generate tool definitions
  187. yarn build # Build the server
  188. yarn build:all # Generate tools and build
  189. yarn dev # Run with hot reload
  190. yarn type-check # Type check without emitting
  191. yarn start # Start the server
  192. ```
  193. ### Technology Stack
  194. - **Runtime**: Node.js with tsx for TypeScript execution
  195. - **Package Manager**: Yarn 4.9.2 with Plug'n'Play
  196. - **Build System**: Simple TypeScript compilation to single file
  197. - **Language**: TypeScript 5.3+
  198. - **MCP SDK**: @modelcontextprotocol/sdk
  199. - **API Client**: @richard-stovall/opnsense-typescript-client
  200. - **Validation**: Zod for schema validation
  201. - **Testing**: Jest with TypeScript support
  202. ## API Integration
  203. The server uses the [@richard-stovall/opnsense-typescript-client](https://www.npmjs.com/package/@richard-stovall/opnsense-typescript-client) package which provides:
  204. - Complete type safety for all API calls
  205. - Built-in error handling and retries
  206. - Support for all 601 OPNsense API endpoints
  207. - Modern Fetch API based implementation
  208. ### Example Tool Implementation
  209. ```typescript
  210. const response = await client.system.getStatus();
  211. return {
  212. content: [
  213. {
  214. type: 'text',
  215. text: JSON.stringify(response.data, null, 2),
  216. },
  217. ],
  218. };
  219. ```
  220. ## Contributing
  221. Contributions are welcome! Please feel free to submit a Pull Request.
  222. 1. Fork the repository
  223. 2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
  224. 3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
  225. 4. Push to the branch (`git push origin feature/AmazingFeature`)
  226. 5. Open a Pull Request
  227. ## License
  228. This project is licensed under the MIT License - see the LICENSE file for details.
  229. ## Acknowledgments
  230. - Built on the [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic
  231. - Powered by [@richard-stovall/opnsense-typescript-client](https://www.npmjs.com/package/@richard-stovall/opnsense-typescript-client)
  232. - Inspired by the OPNsense community
  233. ---
  234. Made with love for the OPNsense community

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.