LibreNMS MCP

LibreNMS MCP Server

Let AI agents query and manage LibreNMS network monitoring through the Model Context Protocol

Installation · Tools · Configuration · Security

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

1. Install dependencies:

# Using UV (recommended)

uv sync

Or using pip

pip install -e .

1. Configure environment variables:

cp .env.example .env

Edit .env with your LibreNMS url and token

1. 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:// :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

SNMP Credential Redaction

Replaces SNMP community and SNMPv3 credentials in API responses with ;

set REDACT_SNMP_CREDENTIALS false to return them as LibreNMS sends them

REDACT_SNMP_CREDENTIALS=true

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

Short Device Names (Optional)

Set RESOLVE_SHORT_HOSTNAMES true to accept a device's short name ("rtr1") where

a hostname is expected, resolving it to the one device whose hostname, up to the

first dot, or whose sysName equals it (ignoring case)

RESOLVE_SHORT_HOSTNAMES=false

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_wireless_sensors: List wireless sensors (frequency, clients, rssi, ...) with current values
• device_parents_set: Set the dependency parents of a device (replaces the current set)
• device_parents_clear: Remove dependency parents from 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 `p