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.

• 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

• 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

• Rate limiting and API security features
• Real-time network monitoring and health tracking
• Comprehensive logging and audit trails
• SSL/TLS support and configurable timeouts
• Extensible with custom middlewares and utilities

• Python 3.11 or higher
• Access to a LibreNMS
• Valid LibreNMS token with appropriate permissions

1. Clone the repository:

git clone https://github.com/mhajder/librenms-mcp.git
cd librenms-mcp

2. Install dependencies:

# Using UV (recommended)
uv sync

# Or using pip
pip install -e .

3. Configure environment variables:

cp .env.example .env
# Edit .env with your LibreNMS url and token

4. Run the server:

# Using UV
uv run python run_server.py

# Or directly with Python
python run_server.py

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 .

# Setup pre-commit hooks
uv run pre-commit install

# 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

# 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

# Using UV
uv run python run_server.py

# Or directly with Python
python run_server.py

• 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_availability: Get device availability
• device_outages: Get device outages
• device_set_maintenance: Set device maintenance mode
• 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

• ports_list: List all ports (with optional filters)
• 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

• 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
• logs_eventlog: Get event log for a device
• logs_syslog: Get syslog for a device
• logs_alertlog: Get alert log for a device
• logs_authlog: Get auth log for a device
• logs_syslogsink: Add a syslog sink

• bills_list: List bills
• bill_get: Get details for a bill
• bill_graph: Get bill graph
• bill_graph_data: Get bill graph data
• bill_history: Get bill history
• bill_history_graph: Get bill history graph
• bill_history_graph_data: Get bill history graph data
• bill_create_or_update: Create or update a bill
• bill_delete: Delete a bill

• 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.
• 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.)

The server supports a read-only mode that disables all write operations for safe monitoring:

READ_ONLY_MODE=true

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.

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

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and ensure code quality (uv run pytest && uv run ruff check .)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

MIT License - see LICENSE file for details.