使用说明

clr-librenms-mcp

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.