Clr Librenms

PyPI License: MIT Python 3.11+

MCP server for LibreNMS network monitoring — query devices, alerts, sensors, ports, and more through AI assistants like Claude.

Features

• Device monitoring — list devices, health summary, availability, outages, down devices
• Alert management — list, filter, acknowledge alerts, alert rules
• Sensor data — health sensors by device and type (temperature, voltage, fan, etc.)
• Port/interface info — list ports, search by name, find by MAC address
• ARP & FDB lookups — resolve IPs to MACs, find MAC on switch ports
• Hardware inventory — chassis, modules, power supplies, serial numbers
• IP address management — list IPs assigned to devices
• Token-based auth — simple X-Auth-Token authentication

Installation

pip install clr-librenms-mcp
# or
uvx clr-librenms-mcp

Configuration

Preferred: Configuration file at ~/.config/librenms/credentials.json (chmod 600):

{
  "url": "https://librenms.example.com",
  "token": "your-api-token"
}

Alternative: Environment variables are also supported:

Variable	Description	Example
LIBRENMS_URL	LibreNMS base URL	https://librenms.example.com
LIBRENMS_TOKEN	API token (generate in LibreNMS UI under API Settings)	abc123...

Optional:

Variable	Description	Default
LIBRENMS_READ_ONLY	Run in read-only mode	false
LIBRENMS_TRANSPORT	Transport protocol (stdio or http)	stdio
LIBRENMS_LOG_LEVEL	Log level	INFO

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "librenms": {
      "command": "uvx",
      "args": ["clr-librenms-mcp"]
    }
  }
}

Claude Code

Add via CLI:

claude mcp add librenms -- uvx clr-librenms-mcp

Or add to your .mcp.json:

{
  "librenms": {
    "command": "uvx",
    "args": ["clr-librenms-mcp"]
  }
}

VS Code

Add to your VS Code settings or .vscode/mcp.json:

{
  "mcp": {
    "servers": {
      "librenms": {
        "command": "uvx",
        "args": ["clr-librenms-mcp"]
      }
    }
  }
}

Note: Configuration is read from ~/.config/librenms/credentials.json or environment variables. No need to specify credentials in MCP config files.

HTTP Transport

To run as a standalone HTTP server:

clr-librenms-mcp --transport http --host 0.0.0.0 --port 8000

Tools

System

Tool	Description
system	Get LibreNMS version and system information

Devices

Tool	Description	Parameters
list_devices	List all monitored devices	device_type?, query?
get_device	Get full detail for a single device	device
down_devices	List all devices currently down	—
device_summary	Aggregate status summary (up/down/disabled)	—
device_availability	Availability percentages (24h, 7d, 30d, 365d)	device
device_outages	Outage history for a device	device
device_ips	IP addresses assigned to a device	device
inventory	Hardware inventory (chassis, modules, PSUs)	device, physical_class?

Alerts

Tool	Description	Parameters
list_alerts	List alerts with optional filters	state?, severity?
get_alert	Get full detail for a single alert	alert_id
alert_count	Alert count by state and severity	—
ack_alert	Acknowledge an alert	alert_id, note?
list_alert_rules	List all alert rules	—

Alert filter values:

Parameter	Accepted values
state	active, acknowledged, resolved
severity	ok, warning, critical

Sensors & Health

Tool	Description	Parameters
list_sensors	List all sensors or filter by device	device?
device_health	Health sensors for a device by type	device, health_type?

Health types: temperature, voltage, fanspeed, power, humidity, state, and more.

Ports & Interfaces

Tool	Description	Parameters
list_ports	List ports/interfaces for a device	device
search_ports	Search ports by name, alias, or description	search
port_by_mac	Find port(s) by MAC address	mac

Network Lookups

Tool	Description	Parameters
arp_lookup	ARP lookup by IP, MAC, or CIDR	query, device?
fdb	MAC/FDB table for a device	device

Example Usage

Once connected, you can ask your AI assistant things like:

• "Are any devices down in LibreNMS?"
• "Show me all critical alerts"
• "What are the temperature sensors on router01?"
• "Find which switch port has MAC aa:bb:cc:dd:ee:ff"
• "What's the availability for switch01 over the last 30 days?"
• "Acknowledge alert 42"
• "Show me the ARP table for 10.0.0.0/24"
• "List the hardware inventory for core-switch"

Safety

All tools are read-only except ack_alert, which is a non-destructive write operation — it marks an alert as acknowledged but does not modify device configuration or monitoring state.

Technical Notes

• Auth: Token-based via X-Auth-Token header (generate tokens in LibreNMS under API Settings)
• API version: Uses LibreNMS REST API v0
• Device parameter: Most tools accept hostname, IP address, or device_id interchangeably
• Sensors: Use device_health with health_type for filtered sensor views, or list_sensors for all sensors across all devices

Development

git clone https://github.com/clearminds/clr-librenms-mcp.git
cd clr-librenms-mcp
uv sync
uv run clr-librenms-mcp

License

MIT — see LICENSE for details.