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 文件。