Overview

OPNSense MCP Server is an intermediary service designed to simplify and secure programmatic interaction with one or more OPNsense firewall instances. It implements a Model Context Protocol (MCP) style API surface that standardizes requests, centralizes authentication, and provides a lightweight layer for orchestration, audit logging, and request transformation. For developers and operators, the server reduces repetitive API plumbing and lets you focus on higher-level automation and integration tasks.

Typical deployments place the MCP server in a trusted management network where it can reach OPNsense APIs. Clients talk to the MCP server using a stable REST API, while the server handles the details of OPNsense sessions, rate limiting, TLS, and policy checks. This makes it easier to manage firewall rules, monitor system state, and expose controlled API access to internal tools or automation pipelines.

Features

Centralized proxying and transformation for OPNsense REST API calls
Token-based authentication and role-aware access control
TLS support for secure client connections
Rate limiting and request throttling per-client or per-endpoint
Request/response logging and audit trail for compliance
Configurable mappings to translate MCP requests into OPNsense API calls
Docker-friendly deployment and a systemd unit example for bare-metal installs
Basic health, metrics, and status endpoints for monitoring

Installation / Configuration

The server can be run via Docker or installed from source. Below are common setup examples.

Clone and run locally:

git clone https://github.com/vespo92/OPNSenseMCP.git
cd OPNSenseMCP
# build (if provided) or run with Python
docker build -t opsense-mcp .

Docker Compose example:

version: "3.7"
services:
  opsense-mcp:
    image: vespo92/opsense-mcp:latest
    restart: unless-stopped
    ports:
      - "8443:8443"
    environment:
      - MCP_API_TOKEN=supersecrettoken
      - TLS_CERT=/certs/server.crt
      - TLS_KEY=/certs/server.key
    volumes:
      - ./config:/app/config
      - ./certs:/certs:ro

Environment configuration (common variables):

MCP_API_TOKEN: token for clients to authenticate to the MCP server
OPN_HOST_xxx: connection entries for backend OPNsense instances
RATE_LIMIT: requests per second default
LOG_LEVEL: debug/info/warn/error

Example YAML config (config/mcp.yml):

server:
  bind: 0.0.0.0
  port: 8443
  tls:
    cert: /certs/server.crt
    key: /certs/server.key

backends:
  - name: opsense-1
    host: https://opnsense-1.local
    api_key: YOUR_OPNSENSE_KEY
    api_secret: YOUR_OPNSENSE_SECRET

security:
  token_store: file
  admin_tokens:
    - token: supersecrettoken
      roles: [admin]

Systemd unit example:

[Unit]
Description=OPNSense MCP Server
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/docker run --rm -p 8443:8443 -v /etc/mcp:/app/config vespo92/opsense-mcp:latest
Restart=on-failure

[Install]
WantedBy=multi-user.target

Available Resources

GitHub repository: https://github.com/vespo92/OPNSenseMCP — source, issues, and releases
Configuration examples: config/ directory in the repo (contains sample YAMLs and TLS instructions)
Health & metrics endpoints: /health, /metrics (Prometheus)
Audit logs: written to configurable file or syslog
API docs: OpenAPI/Swagger spec bundled or generated by the server (check /docs or /openapi.json)

Use Cases

Centralized rule deployment across multiple OPNsense instances
- Push a firewall rule template to the MCP server; the server applies required transformations and calls the OPNsense APIs for each target host. This reduces duplicated automation logic in CI/CD pipelines.
Secure programmatic access for internal tools
- Instead of distributing OPNsense API keys to multiple services or engineers, grant them scoped access tokens to the MCP server. Tokens can be revoked or rotated centrally.
Audited emergency changes
- Use a role-aware admin token to perform urgent rule changes; the MCP server logs the entire request/response cycle for later review.
ChatOps and scripted orchestration
- Integrate the MCP server with chatbots or orchestration tools. Example: a script calls the MCP endpoint to enable a temporary SSH passthrough rule for a maintenance window; the server enforces TTL and automatically removes the rule if configured.

Concrete example: retrieve active firewall rules via curl

curl -H "Authorization: Bearer supersecrettoken" \
  "https://mcp.example.local:8443/api/v1/firewall/rules?backend=opsense-1"

Apply a new rule (JSON payload):

curl -X POST -H "Authorization: Bearer supersecrettoken" \
  -H "Content-Type: application/json" \
  -d @new-rule.json \
  "https://mcp.example.local:8443/api/v1/firewall/rules?backend=opsense-1"

Tips & Best Practices

Use TLS for all client connections and validate certificates when possible.
Store backend OPNsense credentials securely (environment secrets, vault).
Enable metrics and integrate with Prometheus/Grafana for observability.
Limit admin token usage and prefer scoped tokens for automation jobs.
Regularly rotate both MCP and OPNsense API credentials and monitor audit logs for anomalies.

For source, issues, and contribution guidelines, see the repository on GitHub: https://github.com/vespo92/OPNSenseMCP.

OPNSense MCP Server: Firewall & API Management