Librenms MCP

🚀 LibreNMS MCP Server

LibreNMS MCP Server 是一個基於 Python 的模型上下文協議（MCP）服務器，旨在為 LibreNMS 網絡監控數據和管理功能提供高級的可編程訪問。它提供了一個現代化的 API，用於查詢、自動化和集成 LibreNMS 資源，如設備、端口、警報、庫存、位置、日誌等。該服務器支持讀寫操作，具備強大的安全功能，適合與自動化工具、儀表盤和自定義網絡管理工作流程集成。

🚀 快速開始

LibreNMS MCP Server 為用戶提供了便捷的方式來訪問和管理 LibreNMS 網絡監控數據。你可以通過以下步驟快速開啟使用之旅。

✨ 主要特性

核心特性

• 可靈活過濾查詢 LibreNMS 設備、端口、庫存、位置、日誌和警報。
• 獲取網絡拓撲、設備狀態和性能指標。
• 訪問和分析警報歷史、事件日誌和系統健康狀況。
• 監控接口統計信息、端口狀態和流量數據。
• 通過 MAC 或 IP 地址跟蹤端點和連接設備。
• 檢索和管理設備組、端口組和輪詢器組。
• 獲取有關網絡服務和路由的詳細信息。

管理操作

• 創建、更新和刪除設備、端口和組（如果啟用）。
• 管理警報規則、通知和設備元數據。
• 配置只讀模式，限制所有寫操作，以實現安全監控。
• 支持對設備和端口進行批量操作。

高級功能

• 速率限制和 API 安全功能。
• 即時網絡監控和健康跟蹤。
• 全面的日誌記錄和審計跟蹤。
• 支持 SSL/TLS 和可配置的超時設置。
• 可通過自定義中間件和實用程序進行擴展。

📦 安裝指南

前提條件

• Python 3.11 至 3.14
• 能夠訪問 LibreNMS
• 具有適當權限的有效 LibreNMS 令牌

從 PyPI 快速安裝

最簡單的開始方式是從 PyPI 安裝：

# 使用 UV（推薦）
uvx librenms-mcp

# 或者使用 pip
pip install librenms-mcp

在運行服務器之前，請記得為你的 LibreNMS 實例配置環境變量：

# 創建環境配置
export LIBRENMS_URL=https://domain.tld:8443
export LIBRENMS_TOKEN=your-librenms-token

更多詳細信息，請訪問：https://pypi.org/project/librenms-mcp/

從源代碼安裝

1. 克隆倉庫：

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

2. 安裝依賴項：

# 使用 UV（推薦）
uv sync

# 或者使用 pip
pip install -e .

3. 配置環境變量：

cp .env.example .env
# 使用你的 LibreNMS URL 和令牌編輯 .env

4. 運行服務器：

# 使用 UV
uv run python run_server.py

# 或者直接使用 Python
python run_server.py

# 或者使用已安裝的腳本
librenms-mcp

使用 Docker

GitHub Packages 上提供了 Docker 鏡像，便於部署。

# 普通 STDIO 鏡像
docker pull ghcr.io/mhajder/librenms-mcp:latest

# 用於 Open WebUI 的 MCPO 鏡像
docker pull ghcr.io/mhajder/librenms-mcpo:latest

開發環境設置

若要使用額外工具進行開發：

# 克隆並安裝開發依賴項
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

📚 詳細文檔

配置

環境變量

# LibreNMS 連接詳細信息
LIBRENMS_URL=https://domain.tld:8443
LIBRENMS_TOKEN=your-librenms-token

# SSL 配置
LIBRENMS_VERIFY_SSL=true
LIBRENMS_TIMEOUT=30

# 只讀模式
# 將 READ_ONLY_MODE 設置為 true 以禁用所有寫操作（put、post、delete）
READ_ONLY_MODE=false

# 禁用的標籤
# 以逗號分隔的標籤列表，用於禁用工具（默認為空）
# 示例：DISABLED_TAGS=alert,bills
DISABLED_TAGS=

# 日誌配置
LOG_LEVEL=INFO

# 速率限制（每分鐘請求數）
# 將 RATE_LIMIT_ENABLED 設置為 true 以啟用速率限制
RATE_LIMIT_ENABLED=false
RATE_LIMIT_MAX_REQUESTS=100
RATE_LIMIT_WINDOW_MINUTES=1

# Sentry 錯誤跟蹤（可選）
# 設置 SENTRY_DSN 以啟用錯誤跟蹤和性能監控
# SENTRY_DSN=https://your-key@o12345.ingest.us.sentry.io/6789
# 可選的 Sentry 配置
# SENTRY_TRACES_SAMPLE_RATE=1.0
# SENTRY_SEND_DEFAULT_PII=true
# SENTRY_ENVIRONMENT=production
# SENTRY_RELEASE=1.2.3
# SENTRY_PROFILE_SESSION_SAMPLE_RATE=1.0
# SENTRY_PROFILE_LIFECYCLE=trace
# SENTRY_ENABLE_LOGS=true

# MCP 傳輸配置
# 傳輸類型：'stdio'（默認）、'sse'（服務器發送事件）或 'http'（HTTP 可流式傳輸）
MCP_TRANSPORT=stdio

# HTTP 傳輸設置（當 MCP_TRANSPORT=sse 或 MCP_TRANSPORT=http 時使用）
# 綁定 HTTP 服務器的主機（默認：0.0.0.0 表示所有接口）
MCP_HTTP_HOST=0.0.0.0
# 綁定 HTTP 服務器的端口（默認：8000）
MCP_HTTP_PORT=8000
# 可選的用於身份驗證的承載令牌（留空表示無需認證）
MCP_HTTP_BEARER_TOKEN=

可用工具

設備與庫存工具

• devices_list：列出所有設備（可選過濾）
• device_get：獲取特定設備的詳細信息
• device_add：添加新設備
• device_update：更新設備元數據
• device_delete：移除設備
• device_ports：列出設備的所有端口
• device_ports_get：獲取設備特定端口的詳細信息
• device_availability：獲取設備可用性
• device_outages：獲取設備故障信息
• device_set_maintenance：設置設備維護模式
• device_discover：使用提供的憑據發現或添加設備
• device_rename：重命名現有設備
• device_maintenance_status：獲取設備的維護狀態
• device_vlans：列出設備的 VLAN
• device_links：列出設備的鏈接
• device_eventlog_add：為設備添加事件日誌條目
• inventory_device：獲取設備的庫存信息
• inventory_device_flat：獲取設備的扁平庫存信息
• devicegroups_list：列出設備組
• devicegroup_add：添加設備組
• devicegroup_update：更新設備組
• devicegroup_delete：刪除設備組
• devicegroup_devices：列出設備組中的設備
• devicegroup_set_maintenance：設置設備組的維護狀態
• devicegroup_add_devices：向設備組添加設備
• devicegroup_remove_devices：從設備組移除設備
• locations_list：列出所有位置
• location_add：添加位置
• location_edit：編輯位置
• location_delete：刪除位置
• location_get：獲取位置的詳細信息
• location_set_maintenance：設置位置的維護狀態

端口與端口組工具

• ports_list：列出所有端口（可選過濾）
• ports_search：搜索端口（通用搜索）
• ports_search_field：按特定字段搜索端口
• ports_search_mac：按 MAC 地址搜索端口
• port_get：獲取特定端口的詳細信息
• port_ip_info：獲取端口的 IP 地址信息
• port_transceiver：獲取端口的收發器信息
• port_description_get：獲取端口描述
• port_description_update：更新端口描述
• port_groups_list：列出端口組
• port_group_add：添加端口組
• port_group_list_ports：列出端口組中的端口
• port_group_assign：將端口分配給端口組
• port_group_remove：從端口組移除端口

警報與日誌工具

• alerts_get：列出當前和歷史警報
• alert_get_by_id：獲取特定警報的詳細信息
• alert_acknowledge：確認警報
• alert_unmute：取消警報靜音
• alert_rules_list：列出警報規則
• alert_rule_get：獲取特定警報規則的詳細信息
• alert_rule_add：添加警報規則
• alert_rule_edit：編輯警報規則
• alert_rule_delete：刪除警報規則
• alert_templates_list：列出所有警報模板
• alert_template_get：獲取特定警報模板
• alert_template_create：創建新的警報模板
• alert_template_edit：編輯警報模板
• alert_template_delete：刪除警報模板
• logs_eventlog：獲取設備的事件日誌
• logs_syslog：獲取設備的系統日誌
• logs_alertlog：獲取設備的警報日誌
• logs_authlog：獲取設備的認證日誌
• logs_syslogsink：添加系統日誌接收器

計費工具

• bills_list：列出賬單
• bill_get：獲取賬單的詳細信息
• bill_graph：獲取賬單圖表
• bill_graph_data：獲取賬單圖表數據
• bill_history：獲取賬單歷史記錄
• bill_history_graph：獲取賬單歷史圖表
• bill_history_graph_data：獲取賬單歷史圖表數據
• bill_create_or_update：創建或更新賬單
• bill_delete：刪除賬單

網絡與監控工具

• arp_search：搜索 ARP 條目
• poller_group_get：獲取輪詢器組
• routing_ip_addresses：列出 LibreNMS 中的所有 IP 地址。
• services_list：列出 LibreNMS 中的所有服務。
• services_for_device：從 LibreNMS 獲取設備的服務。
• service_add：向 LibreNMS 添加服務
• service_edit：編輯現有服務
• service_delete：刪除服務
• bgp_sessions：列出 BGP 會話
• bgp_session_get：獲取特定 BGP 會話的詳細信息
• bgp_session_edit：編輯 BGP 會話
• fdb_lookup：查找轉發數據庫（FDB）條目
• ospf_list：列出 OSPF 實例
• ospf_ports：列出 OSPF 端口
• vrf_list：列出 VRF
• ping：ping LibreNMS 系統
• health_list：列出健康傳感器
• health_by_type：按類型列出健康傳感器
• health_sensor_get：獲取健康傳感器的詳細信息
• sensors_list：列出傳感器
• switching_vlans：列出 LibreNMS 中的所有 VLAN。
• switching_links：列出 LibreNMS 中的所有鏈接。
• system_info：從 LibreNMS 獲取系統信息。

通用查詢工具

• 可對所有主要資源（設備、端口、警報、日誌、庫存等）進行靈活過濾和搜索。

安全與安全特性

只讀模式

服務器支持只讀模式，該模式會禁用所有寫操作，以實現安全監控：

READ_ONLY_MODE=true

基於標籤的工具過濾

你可以通過設置禁用標籤來禁用特定類別的工具：

DISABLED_TAGS=alert,bills

速率限制

服務器支持速率限制，以控制 API 使用並防止濫用。如果啟用，將使用滑動窗口算法對每個客戶端的請求進行限制。 在 .env 文件中設置以下環境變量以啟用速率限制：

RATE_LIMIT_ENABLED=true
RATE_LIMIT_MAX_REQUESTS=100   # 每個窗口允許的最大請求數
RATE_LIMIT_WINDOW_MINUTES=1   # 窗口大小（分鐘）

如果 RATE_LIMIT_ENABLED 設置為 true，服務器將應用速率限制中間件。根據你的環境需要調整 RATE_LIMIT_MAX_REQUESTS 和 RATE_LIMIT_WINDOW_MINUTES。

Sentry 錯誤跟蹤與監控（可選）

服務器可選支持 Sentry 進行錯誤跟蹤、性能監控和調試。Sentry 集成完全是可選的，只有在配置後才會初始化。

安裝

要啟用 Sentry 監控，請安裝可選依賴項：

# 使用 UV（推薦）
uv sync --extra sentry

配置

在 .env 文件中設置 SENTRY_DSN 環境變量以啟用 Sentry：

# 必需：項目的 Sentry DSN
SENTRY_DSN=https://your-key@o12345.ingest.us.sentry.io/6789

# 可選：性能監控採樣率（0.0 - 1.0，默認：1.0）
SENTRY_TRACES_SAMPLE_RATE=1.0

# 可選：包含個人身份信息（默認：true）
SENTRY_SEND_DEFAULT_PII=true

# 可選：環境名稱（例如，"production"、"staging"）
SENTRY_ENVIRONMENT=production

# 可選：發佈版本（如果未設置，則從包中自動檢測）
SENTRY_RELEASE=1.2.2

# 可選：分析 - 連續分析採樣率（0.0 - 1.0，默認：1.0）
SENTRY_PROFILE_SESSION_SAMPLE_RATE=1.0

# 可選：分析 - 分析的生命週期模式（默認："trace"）
# 選項："all"、"continuation"、"trace"
SENTRY_PROFILE_LIFECYCLE=trace

# 可選：啟用日誌捕獲作為麵包屑和事件（默認：true）
SENTRY_ENABLE_LOGS=true

功能

啟用後，Sentry 會自動捕獲：

• 異常與錯誤：所有未處理的異常及完整上下文
• 性能指標：請求/響應時間和跟蹤信息
• MCP 集成：詳細的 MCP 服務器活動和交互信息
• 日誌與麵包屑：應用程序日誌和事件跟蹤，用於調試
• 上下文數據：環境、客戶端信息和請求參數

獲取 Sentry DSN

1. 在 sentry.io 創建免費賬戶
2. 創建新的 Python 項目
3. 從項目設置中複製你的 DSN
4. 在 .env 文件中設置該 DSN

禁用 Sentry

Sentry 是完全可選的。如果你不設置 SENTRY_DSN，服務器將正常運行，不會有任何 Sentry 集成，也不會收集任何監控數據。

SSL/TLS 配置

服務器支持 SSL 證書驗證和自定義超時設置：

LIBRENMS_VERIFY_SSL=true    # 啟用 SSL 證書驗證
LIBRENMS_TIMEOUT=30         # 連接超時時間（秒）

傳輸配置

服務器支持 MCP 協議的多種傳輸機制：

STDIO 傳輸（默認）

默認傳輸使用標準輸入/輸出進行通信。這非常適合本地使用以及與通過 stdin/stdout 進行通信的工具集成：

MCP_TRANSPORT=stdio

HTTP SSE 傳輸（服務器發送事件）

對於基於網絡的部署，你可以使用帶有服務器發送事件的 HTTP。這允許通過 HTTP 即時流式訪問 MCP 服務器：

MCP_TRANSPORT=sse
MCP_HTTP_HOST=0.0.0.0        # 綁定到所有接口（或特定 IP）
MCP_HTTP_PORT=8000           # 監聽端口
MCP_HTTP_BEARER_TOKEN=your-secret-token  # 可選的認證令牌

使用帶有承載令牌的 SSE 傳輸時，客戶端必須在請求中包含該令牌：

curl -H "Authorization: Bearer your-secret-token" http://localhost:8000/sse

HTTP 可流式傳輸傳輸

HTTP 可流式傳輸傳輸提供基於 HTTP 的請求/響應流式通信。這非常適合 Web 集成和需要 HTTP 端點的工具：

MCP_TRANSPORT=http
MCP_HTTP_HOST=0.0.0.0        # 綁定到所有接口（或特定 IP）
MCP_HTTP_PORT=8000           # 監聽端口
MCP_HTTP_BEARER_TOKEN=your-secret-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

注意：HTTP 傳輸需要使用 jsonrpc 和 id 字段進行正確的 JSON-RPC 格式化。某些操作可能還需要服務器進行會話初始化。 有關 FastMCP 傳輸的更多信息，請參閱 FastMCP 文檔。

🤝 貢獻指南

1. 分叉倉庫
2. 創建功能分支 (git checkout -b feature/amazing-feature)
3. 進行更改
4. 運行測試並確保代碼質量 (uv run pytest && uv run ruff check .)
5. 提交更改 (git commit -m 'Add amazing feature')
6. 推送到分支 (git push origin feature/amazing-feature)
7. 打開拉取請求

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。