LibreNMS MCP Server for Monitoring and Management

Overview

The LibreNMS MCP Server is a lightweight service that exposes network context and management operations from a LibreNMS installation through a simple HTTP API compatible with Model Context Protocol (MCP) workflows. It centralizes device metadata, alert history, and performance metrics so downstream tools — chatbots, automation services, or observability platforms — can query current network state and trigger safe actions without direct LibreNMS integration logic.

For developers, the server acts as a bridge: it converts LibreNMS API data into structured context bundles and provides action endpoints (for example, rebooting a device or triggering a configuration backup) guarded by API keys and role-based action whitelists. This makes it practical to add network-aware capabilities to AI assistants, runbooks, and automation pipelines while keeping authentication and auditing consolidated.

Features

• Fetches device inventory, alert history, and performance metrics from LibreNMS
• Exposes a consistent MCP-style HTTP API for context retrieval and action invocation
• Action whitelist and rate-limiting to protect device operations
• Polling and caching of common queries to reduce LibreNMS load
• Configurable authentication (API keys / tokens)
• Docker-friendly with an example docker-compose configuration
• Structured logging and configurable verbosity for integration into CI/CD and observability

Installation / Configuration

Prerequisites: Docker and docker-compose are recommended. The repository includes a Dockerfile and docker-compose example to get started quickly. Replace environment values with your LibreNMS instance details.

1. Clone the repository:

git clone https://github.com/mhajder/librenms-mcp.git
cd librenms-mcp

2. Example environment file (.env):

# .env
LIBRENMS_URL=https://librenms.example.local
LIBRENMS_API_TOKEN=your_librenms_api_token
MCP_API_KEY=supersecretapikey
SERVER_PORT=8080
POLL_INTERVAL_SECONDS=60
ALLOWED_ACTIONS=reboot,backup-config
LOG_LEVEL=info

3. Example docker-compose.yml:

version: "3.8"
services:
  mcp-server:
    build: .
    image: librenms/mcp-server:latest
    restart: unless-stopped
    env_file:
      - .env
    ports:
      - "${SERVER_PORT:-8080}:8080"
    volumes:
      - ./config:/app/config

4. Start with Docker Compose:

docker-compose up -d

5. If running from source, consult the repository for runtime requirements (Node/Python/etc.) and start commands. Typically this means installing dependencies and running the included start script:

# pseudo-example; confirm exact commands in repo
npm install
npm run start

Available Resources

The server exposes REST endpoints for querying context and invoking actions. Below is a representative set of endpoints — consult the repository or the running server’s OpenAPI documentation for exact schemas.

Example: fetch a device context

curl -H "Authorization: Bearer ${MCP_API_KEY}" \
  "http://localhost:8080/api/devices/123"

Invoke an action (reboot):

curl -X POST -H "Authorization: Bearer ${MCP_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"device_id":123,"action":"reboot","reason":"automated-remediation"}' \
  http://localhost:8080/api/actions

Use Cases

• Enriching AI assistants: Provide detailed device context (interfaces, recent alerts, SLA metrics) to an LLM so it can generate safer, context-aware troubleshooting steps or runbooks.
• Centralized alert handling: Aggregate LibreNMS alerts into a single resource that automation pipelines can poll to prioritize incidents and trigger mitigation actions.
• Automated remediation: Combine detection rules with the server’s action API to run validated remediation (soft reboots, interface shutdown/enable, scheduled config backup) while keeping an audit trail.
• Performance troubleshooting: Pull recent time-series metrics for an endpoint to feed into anomaly-detection models or diagnostic tooling, avoiding direct LibreNMS query load spikes.
• Integration with chatops: Allow chat applications to request a device context or invoke whitelisted actions through the MCP server without exposing LibreNMS credentials to every bot.

Getting Help and Resources

• Source & issues: https://github.com/mhajder/librenms-mcp
• Configuration tips:
  • Tune POLL_INTERVAL_SECONDS and cache TTLs to balance freshness vs. LibreNMS API limits.
  • Use per-service API keys and narrow ALLOWED_ACTIONS to reduce blast radius