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:
uvx librenms-mcp
pip install librenms-mcp
Remember to configure the environment variables for your LibreNMS instance before running the server:
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
- Clone the repository:
git clone https://github.com/mhajder/librenms-mcp.git
cd librenms-mcp
- Install dependencies:
- Configure environment variables:
- Run the server:
uv run librenms-mcp
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:
git clone https://github.com/mhajder/librenms-mcp.git
cd librenms-mcp
uv sync --group dev
uv run pytest
uv run pytest --cov=src/
uv run ruff check .
uv run ruff format .
uv run ty check .
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 <redacted>;
# 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=
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
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_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
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.
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
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
bill_history_graph: Render a bill history graph as an image
bill_history_graph_data: Get bill history graph data
bill_create_or_update: Create or update a bill
bill_delete: Delete a bill
oxidized_list: List devices tracked by Oxidized for config backup
oxidized_config_get: Get the stored configuration for a specific device
oxidized_config_search: Search all stored device configurations for a string
-
arp_search: Search ARP entries
-
poller_group_get: Get poller group(s)
-
routing_ip_addresses: List all IP addresses from LibreNMS.
-
services_list: List all services from LibreNMS.
-
services_for_device: Get services for a device from LibreNMS.
-
service_add: Add a service to LibreNMS
-
service_edit: Edit an existing service
-
service_delete: Delete a service
-
bgp_sessions: List BGP sessions
-
bgp_session_get: Get details for a specific BGP session
-
bgp_session_edit: Edit a BGP session
-
fdb_lookup: Lookup forwarding database (FDB) entries
-
nac_list: List network access control (802.1X / MAB) sessions across all devices
-
ospf_list: List OSPF instances
-
ospf_ports: List OSPF ports
-
vrf_list: List VRFs
-
ping: Ping the LibreNMS system
-
health_list: List health sensors
-
health_by_type: List health sensors by type
-
health_sensor_get: Get details for a health sensor
-
sensors_list: List sensors
-
switching_vlans: List all VLANs from LibreNMS.
-
switching_links: List all links from LibreNMS.
-
system_info: Get system info from LibreNMS.
-
Flexible filtering and search for all major resources (devices, ports, alerts, logs, inventory, etc.)
To prevent overloading LLM contexts when querying large LibreNMS production instances, all list, search, and log tools support pagination.
Key Features
- Sensible Defaults: All list tools default to returning 100 results per page.
- Unified Parameters:
limit: The maximum number of results to return (defaults to 100, minimum 1).
offset (or start for log tools): The number of results to skip.
- Pagination Metadata: Every paginated response includes metadata fields:
limit: The active limit.
offset (or start): The active offset.
count: The number of items returned in the current page.
total: The total number of items available (for log tools, this is provided if returned by the LibreNMS API).
π¨ Error Responses
Every tool that returns JSON reports a failure in LibreNMS's own error shape,
whether the error came from LibreNMS, from a check in this server, or from an
exception such as a timeout:
{"status": "error", "message": "Device typo does not exist"}
Check status == "error". Up to 1.11.3, exceptions were returned as
{"error": "..."}; clients that looked for an error key need updating.
π Security & Safety Features
SNMP Credential Redaction
LibreNMS returns the full device record from its device endpoints (get, list
and search), including the SNMP community and the SNMPv3 username and
passphrases in plain text. No tool needs them, and anything a tool returns
ends up in an AI client's context, chat history and traces, so the server
replaces them with <redacted> as soon as a response is decoded:
- the
community, authname, authpass and cryptopass values of device
records (objects with a device_id and a hostname or snmpver);
- the community and SNMPv3 username and passphrase arguments (
-C, -U,
-A, -X and their long forms) in the service_param of snmp
(check_snmp) services;
- the same device values in raw response text quoted in an error message.
Unset values stay as they are, so you can still see whether a credential is
configured; the SNMP version and algorithms are left visible for
troubleshooting. A community field outside a device record (a BGP
community, for instance) is not a credential and is left as is. Credentials
in other services' parameters (such as a check_mysql password) are not
redacted, and credentials sent with device_add are unaffected.
Redaction is on by default. A deployment whose clients need the credentials,
such as a trusted automation, can turn it off:
REDACT_SNMP_CREDENTIALS=false
Read-Only Mode
The server supports a read-only mode that disables all write operations for safe monitoring:
You can disable specific categories of tools by setting disabled tags:
DISABLED_TAGS=alert,alert-rules,alert-templates,bills
A tool is hidden when any of its tags is disabled, and some tools carry more
than one category tag: for example, port_graph is tagged graphs and ports,
and ospf_list is tagged routing and ospf, so DISABLED_TAGS=ports also
hides port_graph. Alerting is split into three tags: alert (current alerts:
list, acknowledge, unmute), alert-rules and alert-templates; disable all
three to hide every alerting tool.
Besides the categories, read-only marks the tools that stay available in
read-only mode. The admin and global-read tags follow the permission groups
older LibreNMS releases used for their API routes (can:admin,
can:global-read). Current LibreNMS checks permissions per object instead, so
treat these two as broad categories rather than an exact match of what your
LibreNMS user may do.
FastMCP tool search can reduce prompt size for servers with many tools.
When enabled, list_tools returns two synthetic tools:
search_tools: Finds matching tools and returns their full schemas
call_tool: Executes any discovered tool by name
Enable it with:
TOOL_SEARCH_ENABLED=true
TOOL_SEARCH_STRATEGY=bm25 # bm25 or regex
TOOL_SEARCH_MAX_RESULTS=5 # optional, default is 5
bm25 supports natural language queries, while regex uses a regex pattern input for deterministic matching.
Tool search respects existing visibility controls (read-only mode and disabled tags).
Short Device Names
LibreNMS matches devices by their full hostname or ID, so a call naming a
device by its short name (rtr1 for rtr1.dc1.example.net) answers
"Device rtr1 does not exist". With
RESOLVE_SHORT_HOSTNAMES=true
a bare short name in a tool's hostname or device argument is replaced by
the stored hostname of the one device whose hostname, up to the first dot, or
whose sysName equals it (ignoring case), so a device added by IP is found by
its sysName. A device whose stored hostname is the name itself always wins,
so calls that already worked keep working. Surrounding whitespace is ignored.
This costs two devices searches (hostname and sysName) per call that uses a
short name. Names containing a dot or a colon (FQDNs, IP addresses) and
device IDs are sent as given, a name that matches no device is left for the
tool to report, and a name that matches several devices is refused with a
tool error listing the candidates.
Rate Limiting
The server supports rate limiting to control API usage and prevent abuse. If enabled, requests are limited per client using a sliding window algorithm.
Enable rate limiting by setting the following environment variables in your .env file:
RATE_LIMIT_ENABLED=true
RATE_LIMIT_MAX_REQUESTS=100 # Maximum requests allowed per window
RATE_LIMIT_WINDOW_MINUTES=1 # Window size in minutes
If RATE_LIMIT_ENABLED is set to true, the server will apply rate limiting middleware. Adjust RATE_LIMIT_MAX_REQUESTS and RATE_LIMIT_WINDOW_MINUTES as needed for your environment.
Sentry Error Tracking & Monitoring (Optional)
The server optionally supports Sentry for error tracking, performance monitoring, and debugging. Sentry integration is completely optional and only initialized if configured.
Installation
To enable Sentry monitoring, install the optional dependency:
Configuration
Enable Sentry by setting the SENTRY_DSN environment variable in your .env file:
# Required: Sentry DSN for your project
SENTRY_DSN=https://your-key@o12345.ingest.us.sentry.io/6789
# Optional: Performance monitoring sample rate (0.0-1.0, default: 1.0)
SENTRY_TRACES_SAMPLE_RATE=1.0
# Optional: Include personally identifiable information (default: false).
# When true, tool inputs and outputs (device configs, SNMP credentials) are sent to Sentry.
SENTRY_SEND_DEFAULT_PII=false
# Optional: Environment name (e.g., "production", "staging")
SENTRY_ENVIRONMENT=production
# Optional: Release version (auto-detected from package if not set)
SENTRY_RELEASE=1.2.2
# Optional: Profiling - continuous profiling sample rate (0.0-1.0, default: 1.0)
SENTRY_PROFILE_SESSION_SAMPLE_RATE=1.0
# Optional: Profiling - lifecycle mode for profiling (default: "trace")
# Options: "all", "continuation", "trace"
SENTRY_PROFILE_LIFECYCLE=trace
# Optional: Enable log capture as breadcrumbs and events (default: true)
SENTRY_ENABLE_LOGS=true
Features
When enabled, Sentry automatically captures:
- Exceptions & Errors: All unhandled exceptions with full context
- Performance Metrics: Request/response times and traces
- MCP Integration: Detailed MCP server activity and interactions
- Logs & Breadcrumbs: Application logs and event trails for debugging
- Context Data: Environment, client info, and request parameters
Getting a Sentry DSN
- Create a free account at sentry.io
- Create a new Python project
- Copy your DSN from the project settings
- Set it in your
.env file
Disabling Sentry
Sentry is completely optional. If you don't set SENTRY_DSN, the server will run normally without any Sentry integration, and no monitoring data will be collected.
SSL/TLS Configuration
The server supports SSL certificate verification and custom timeout settings:
LIBRENMS_VERIFY_SSL=true # Enable SSL certificate verification
LIBRENMS_TIMEOUT=30 # Connection timeout in seconds
Transport Configuration
The server supports multiple transport mechanisms for the MCP protocol. MCP_TRANSPORT is case-insensitive, streamable-http is accepted as an alias for http, and any other value stops the server at startup with an error rather than silently falling back to STDIO:
STDIO Transport (Default)
The default transport uses standard input/output for communication. This is ideal for local usage and integration with tools that communicate via stdin/stdout:
HTTP SSE Transport (Server-Sent Events)
For network-based deployments, you can use HTTP with Server-Sent Events. This allows the MCP server to be accessed over HTTP with real-time streaming:
MCP_TRANSPORT=sse
MCP_HTTP_HOST=127.0.0.1 # Localhost
MCP_HTTP_PORT=8000 # Port to listen on
MCP_HTTP_BEARER_TOKEN=your-secret-token # Optional authentication token
When using SSE transport with a bearer token, clients must include the token in their requests:
curl -H "Authorization: Bearer your-secret-token" http://localhost:8000/sse
HTTP Streamable Transport
The HTTP Streamable transport provides HTTP-based communication with request/response streaming. This is ideal for web integrations and tools that need HTTP endpoints:
MCP_TRANSPORT=http
MCP_HTTP_HOST=127.0.0.1 # Localhost
MCP_HTTP_PORT=8000 # Port to listen on
MCP_HTTP_BEARER_TOKEN=your-secret-token # Optional authentication token
When using streamable transport with a bearer token:
curl -H "Authorization: Bearer your-secret-token" \
-H "Accept: application/json, text/event-stream" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
http://localhost:8000/mcp
Note: The HTTP transport requires proper JSON-RPC formatting with jsonrpc and id fields. The server may also require session initialization for some operations.
Health Endpoint
Both HTTP transports (sse and http) serve GET /health, which answers 200 ok
when the server is handling requests. It needs no bearer token and does not
contact LibreNMS, so a LibreNMS outage does not mark the MCP server unhealthy.
The Docker image's HEALTHCHECK uses it:
curl http://localhost:8000/health
For more information on FastMCP transports, see the FastMCP documentation.
π€ Contributing
Contributions are welcome. See CONTRIBUTING.md for the dev setup, checks and commit message format, and use the issue templates for bugs and feature requests.
Found a security problem? Please report it privately as described in SECURITY.md.
π License
MIT License - see LICENSE for details.