LibreNMS MCP Server

<!-- mcp-name: io.github.mhajder/librenms-mcp -->

LibreNMS MCP Server is a Python-based Model Context Protocol (MCP) server designed to provide advanced, programmable access to LibreNMS network monitoring data and management features. It exposes a modern API for querying, automating, and integrating LibreNMS resources such as devices, ports, alerts, inventory, locations, logs, and more. The server supports both read and write operations, robust security features, and is suitable for integration with automation tools, dashboards, and custom network management workflows.

Features

Core Features

• Query LibreNMS devices, ports, inventory, locations, logs, and alerts with flexible filtering
• Retrieve network topology, device status, and performance metrics
• Access and analyze alert history, event logs, and system health
• Monitor interface statistics, port status, and traffic data
• Track endpoints and connected devices by MAC or IP address
• Retrieve and manage device groups, port groups, and poller groups
• Get detailed information about network services and routing

Management Operations

• Create, update, and delete devices, ports, and groups (if enabled)
• Manage alert rules, notifications, and device metadata
• Configure read-only mode to restrict all write operations for safe monitoring
• Support for bulk operations on devices and ports

Advanced Capabilities

• Rate limiting and API security features
• Real-time network monitoring and health tracking
• Comprehensive logging and audit trails
• SSL/TLS support and configurable timeouts
• Optional tool-search transform for large tool catalogs
• Extensible with custom middlewares and utilities

Installation

Prerequisites

• Python 3.11 to 3.15
• Access to a LibreNMS
• Valid LibreNMS token with appropriate permissions

Quick Install from PyPI

The easiest way to get started is to install from PyPI:

# Using UV (recommended)
uvx librenms-mcp

# Or using pip
pip install librenms-mcp

Remember to configure the environment variables for your LibreNMS instance before running the server:

# Create environment configuration
export LIBRENMS_URL=https://domain.tld:8443
export LIBRENMS_TOKEN=your-librenms-token

For more details, visit: https://pypi.org/project/librenms-mcp/

Install from Source

1. Clone the repository:

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

2. Install dependencies:

# Using UV (recommended)
uv sync

# Or using pip
pip install -e .

3. Configure environment variables:

cp .env.example .env
# Edit .env with your LibreNMS url and token

4. Run the server:

# Using UV (recommended)
uv run librenms-mcp

# Or using the installed command directly
librenms-mcp

Using Docker

A Docker image is available on GitHub Packages for easy deployment. It runs the HTTP Streamable transport on port 8000 (/mcp).

docker pull ghcr.io/mhajder/librenms-mcp:latest

Open WebUI

Open WebUI 0.6.31 and later connect to the image directly; the separate MCPO image (ghcr.io/mhajder/librenms-mcpo) is no longer published. In Open WebUI, go to Admin Settings > Integrations > External Tool Servers, add a connection of type MCP (Streamable HTTP) with the URL http://<host>:8000/mcp, and set Bearer authentication to your MCP_HTTP_BEARER_TOKEN.

Development Setup

For development with additional tools:

# Clone and install with development dependencies
git clone https://github.com/mhajder/librenms-mcp.git
cd librenms-mcp
uv sync --group dev

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/

# Run linting and formatting
uv run ruff check .
uv run ruff format .

# Run type checking
uv run ty check .

# Setup pre-commit hooks
uv run prek install

Configuration

Environment Variables

Boolean settings accept true/false, 1/0, yes/no and on/off (case-insensitive). Any other value stops the server at startup, so a typo cannot silently turn read-only mode or TLS verification off. The exception is SENTRY_SEND_DEFAULT_PII and SENTRY_ENABLE_LOGS: when SENTRY_DSN is set, an invalid value there logs an error and leaves Sentry off, and the server keeps running.

# LibreNMS Connection Details
LIBRENMS_URL=https://domain.tld:8443
LIBRENMS_TOKEN=your-librenms-token

# SSL Configuration
LIBRENMS_VERIFY_SSL=true
LIBRENMS_TIMEOUT=30

# Read-Only Mode
# Set READ_ONLY_MODE true to disable all write operations (put, post, delete)
READ_ONLY_MODE=false

# Disabled Tags
# Comma-separated list of tags to disable tools for (empty by default)
# Example: DISABLED_TAGS=alert,alert-rules,alert-templates,bills
DISABLED_TAGS=

# Logging Configuration
LOG_LEVEL=INFO

# Rate Limiting (requests per minute)
# Set RATE_LIMIT_ENABLED true to enable rate limiting
RATE_LIMIT_ENABLED=false
RATE_LIMIT_MAX_REQUESTS=100
RATE_LIMIT_WINDOW_MINUTES=1

# Tool Search Transform (Optional)
# Set TOOL_SEARCH_ENABLED true to replace full tool listings with search_tools + call_tool
TOOL_SEARCH_ENABLED=false
# Search strategy: bm25 (natural language) or regex (pattern match)
TOOL_SEARCH_STRATEGY=bm25
# Maximum number of tools returned by search_tools
TOOL_SEARCH_MAX_RESULTS=5

# Sentry Error Tracking (Optional)
# Set SENTRY_DSN to enable error tracking and performance monitoring
# SENTRY_DSN=https://your-key@o12345.ingest.us.sentry.io/6789
# Optional Sentry configuration
# SENTRY_TRACES_SAMPLE_RATE=1.0
# SENTRY_SEND_DEFAULT_PII=false
# SENTRY_ENVIRONMENT=production
# SENTRY_RELEASE=1.2.3
# SENTRY_PROFILE_SESSION_SAMPLE_RATE=1.0
# SENTRY_PROFILE_LIFECYCLE=trace
# SENTRY_ENABLE_LOGS=true

# MCP Transport Configuration
# Transport type: 'stdio' (default), 'sse' (Server-Sent Events), or 'http' (HTTP Streamable).
# 'streamable-http' is accepted as an alias for 'http'. Any other value stops the server at startup.
MCP_TRANSPORT=stdio

# HTTP Transport Settings (used when MCP_TRANSPORT=sse or MCP_TRANSPORT=http)
# Host to bind the HTTP server (default: 127.0.0.1)
# MCP_HTTP_HOST=127.0.0.1
# Port to bind the HTTP server (default: 8000)
# MCP_HTTP_PORT=8000
# Optional bearer token for authentication (leave empty for no auth)
# MCP_HTTP_BEARER_TOKEN=

Available Tools

Device & Inventory Tools

• devices_list: List all devices (with optional filters)
• device_get: Get details for a specific device
• device_add: Add a new device
• device_update: Update device metadata
• device_delete: Remove a device
• device_ports: List all ports for a device
• device_ports_get: Get details for a specific port on a device
• device_fdb: List the forwarding database (learned MACs) for a device
• device_nac: List network access control (802.1X / MAB) sessions on a device
• device_availability: Get device availability
• device_outages: Get device outages
• device_set_maintenance: Set device maintenance mode
• device_discover: Discover or add a device using provided credentials
• device_rename: Rename an existing device
• device_maintenance_status: Get the maintenance status for a device
• device_vlans: List VLANs for a device
• device_links: List links for a device
• device_eventlog_add: Add an event log entry for a device
• inventory_device: Get inventory for a device
• inventory_device_flat: Get flat inventory for a device
• devicegroups_list: List device groups
• devicegroup_add: Add a device group
• devicegroup_update: Update a device group
• devicegroup_delete: Delete a device group
• devicegroup_devices: List devices in a device group
• devicegroup_set_maintenance: Set maintenance for a device group
• devicegroup_add_devices: Add devices to a device group
• devicegroup_remove_devices: Remove devices from a device group
• locations_list: List all locations
• location_add: Add a location
• location_edit: Edit a location
• location_delete: Delete a location
• location_get: Get details for a location
• location_set_maintenance: Set maintenance for a location

Port & Port Group Tools

• ports_list: List all ports (with optional filters)
• ports_search: Search ports (general search)
• ports_search_field: Search ports by a specific field
• ports_search_mac: Search ports by MAC address
• port_get: Get details for a specific port
• port_fdb: List MAC addresses learned on a port
• port_ip_info: Get IP address information for a port
• port_transceiver: Get transceiver information for a port
• port_description_get: Get a port description
• port_description_update: Update a port description
• port_groups_list: List port groups
• port_group_add: Add a port group
• port_group_list_ports: List ports in a port group
• port_group_assign: Assign ports to a port group
• port_group_remove: Remove ports from a port group

Port Security Tools

• port_security_list: List port security configuration across all devices
• port_security_device: Get port security configuration for a device
• port_security_port: Get port security configuration for a single port

Graph Tools

Graphs are returned as MCP images. The tools ask LibreNMS for PNG, which MCP clients such as Claude can display (SVG, LibreNMS's default webui.graph_type, often is not). A LibreNMS release that ignores the request renders in its webui.graph_type format instead; the MIME type is taken from the response.

• device_graphs_list: List the graph types available for a device
• device_graph: Render a device-level graph (e.g. device_icmp_perf)
• port_graph: Render a per-port graph by interface name (bits, upkts, nupkts, errors, etherlike; the LibreNMS names such as port_bits are accepted too)
• port_group_graph: Render a traffic graph for one or more ports by port ID

Interface names containing a slash (Te2/7) are sent percent-encoded, and some reverse proxies reject or decode the encoded slash. When that happens, port_graph (for bits) and device_ports_get retry by port ID instead, so they still work behind such a proxy. Authentication errors are never retried, and LibreNMS's own "not found" answers are reported as is for names without a slash (a name with a slash is always retried, since a decoding proxy can turn it into a LibreNMS "not found" for the wrong path).

Other tools that put a slash-bearing value in the path (ports_search, ports_search_field, oxidized_config_search with a prefix such as 0.0.0.0/0, location names) have no such fallback. If LibreNMS sits behind Apache, allow encoded slashes so every tool works:

AllowEncodedSlashes NoDecode

A 400 or 404 for a path with an encoded slash that did not come from LibreNMS includes this hint in the tool's error message.

Alerting & Logging Tools

• alerts_get: List current and historical alerts
• alert_get_by_id: Get details for a specific alert
• alert_acknowledge: Acknowledge an alert
• alert_unmute: Unmute an alert
• alert_rules_list: List alert rules
• alert_rule_get: Get details for a specific alert rule
• alert_rule_add: Add an alert rule
• alert_rule_edit: Edit an alert rule
• alert_rule_delete: Delete an alert rule
• alert_templates_list: List all alert templates
• alert_template_get: Get a specific alert template
• alert_template_create: Create a new alert template
• alert_template_edit: Edit an alert template
• logs_eventlog: Get event log for a device, or for all devices when no hostname is given
• logs_syslog: Get syslog for a device, or for all devices when no hostname is given
• logs_alertlog: Get alert log for a device, or for all devices when no hostname is given
• logs_authlog: Get the server-wide authentication log
• logs_syslogsink: Add a syslog sink

Billing Tools

• bills_list: List bills
• bill_get: Get details for a bill
• bill_graph: Render a bill graph as an image
• bill_graph_data: Get bill graph data
• bill_history: Get bill history