clr-librenms-mcp

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 | |------|-------------| | librenms_system | Get LibreNMS version and system information |

Devices

| Tool | Description | Parameters | |------|-------------|------------| | librenms_list_devices | List all monitored devices | device_type?, query? | | librenms_get_device | Get full detail for a single device | device | | librenms_down_devices | List all devices currently down | — | | librenms_device_summary | Aggregate status summary (up/down/disabled) | — | | librenms_device_availability | Availability percentages (24h, 7d, 30d, 365d) | device | | librenms_device_outages | Outage history for a device | device | | librenms_device_ips | IP addresses assigned to a device | device | | librenms_inventory | Hardware inventory (chassis, modules, PSUs) | device, physical_class? |

Alerts

| Tool | Description | Parameters | |------|-------------|------------| | librenms_list_alerts | List alerts with optional filters | state?, severity? | | librenms_get_alert | Get full detail for a single alert | alert_id | | librenms_alert_count | Alert count by state and severity | — | | librenms_ack_alert | Acknowledge an alert | alert_id, note? | | librenms_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 | |------|-------------|------------| | librenms_list_sensors | List all sensors or filter by device | device? | | librenms_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 | |------|-------------|------------| | librenms_list_ports | List ports/interfaces for a device | device | | librenms_search_ports | Search ports by name, alias, or description | search | | librenms_port_by_mac | Find port(s) by MAC address | mac |

Network Lookups

| Tool | Description | Parameters | |------|-------------|------------| | librenms_arp_lookup | ARP lookup by IP, MAC, or CIDR | query, device? | | librenms_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 librenms_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 librenms_device_health with health_type for filtered sensor views, or librenms_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.