LibreNMS MCP

LibreNMS MCP 服务是一个基于 Python 的模型上下文协议（MCP）服务，旨在提供对 LibreNMS 网络监控数据和管理功能的高级、可编程访问。它提供现代化 API，用于查询、自动化和集成设备、端口、警报、资产清单、位置、日志等 LibreNMS 资源。该服务支持读写操作，具备可靠的安全功能，适合与自动化工具、仪表板和自定义网络管理工作流集成。

✨ 功能

核心功能

• 通过灵活筛选查询 LibreNMS 设备、端口、资产清单、位置、日志和警报
• 获取网络拓扑、设备状态和性能指标
• 访问并分析警报历史记录、事件日志和系统健康状况
• 监控接口统计信息、端口状态和流量数据
• 按 MAC 或 IP 地址跟踪终端和已连接设备
• 获取并管理设备组、端口组和轮询器组
• 获取网络服务和路由的详细信息

管理操作

• 创建、更新和删除设备、端口及组（如已启用）
• 管理警报规则、通知和设备元数据
• 配置只读模式，以限制所有写入操作，确保监控安全
• 支持对设备和端口执行批量操作

高级功能

• 速率限制和 API 安全功能
• 实时网络监控和健康状态跟踪
• 全面的日志记录和审计跟踪
• SSL/TLS 支持和可配置超时
• 可选的工具搜索转换，用于大型工具目录
• 可通过自定义中间件和实用工具扩展

🚀 安装

前提条件

• Python 3.11 至 3.15
• 可访问 LibreNMS
• 具有适当权限的有效 LibreNMS 令牌

从 PyPI 快速安装

最简单的入门方式是从 PyPI 安装：

# Using UV (recommended)
uvx librenms-mcp

# Or using pip
pip install librenms-mcp

运行服务前，请务必为你的 LibreNMS 实例配置环境变量：

# Create environment configuration
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. 安装依赖：

# Using UV (recommended)
uv sync

# Or using pip
pip install -e .

3. 配置环境变量：

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

4. 运行服务：

# Using UV (recommended)
uv run librenms-mcp

# Or using the installed command directly
librenms-mcp

使用 Docker

GitHub Packages 提供 Docker 镜像，方便部署。该镜像通过 8000 端口运行 HTTP Streamable 传输（/mcp）。

docker pull ghcr.io/mhajder/librenms-mcp:latest

Open WebUI

Open WebUI 0.6.31 及更高版本可直接连接到该镜像；不再发布单独的 MCPO 镜像（ghcr.io/mhajder/librenms-mcpo）。在 Open WebUI 中，前往 Admin Settings > Integrations > External Tool Servers，添加一个类型为 MCP (Streamable HTTP) 的连接，URL 设置为 http://<host>:8000/mcp，并将 Bearer 身份验证设置为你的 MCP_HTTP_BEARER_TOKEN。

开发环境设置

如需使用其他工具进行开发：

# 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 .

# Run type checking
uv run ty check .

# Setup pre-commit hooks
uv run prek install

🔧 配置

环境变量

布尔设置接受 true/false、1/0、yes/no 和 on/off（不区分大小写）。任何其他值都会导致服务在启动时停止，因此拼写错误不会在无提示的情况下关闭只读模式或 TLS 验证。例外情况是 SENTRY_SEND_DEFAULT_PII 和 SENTRY_ENABLE_LOGS：当设置了 SENTRY_DSN 时，这些变量的无效值会记录错误并使 Sentry 保持关闭状态，同时服务会继续运行。

# 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

# Disabled Tags
# Comma-separated list of tags to disable tools for (empty by default)
# Example: DISABLED_TAGS=alert,alert-rules,alert-templates,bills
DISABLED_TAGS=

# 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

# Tool Search Transform (Optional)
# Set TOOL_SEARCH_ENABLED true to replace full tool listings with search_tools + call_tool
TOOL_SEARCH_ENABLED=false
# Search strategy: bm25 (natural language) or regex (pattern match)
TOOL_SEARCH_STRATEGY=bm25
# Maximum number of tools returned by search_tools
TOOL_SEARCH_MAX_RESULTS=5

# Sentry Error Tracking (Optional)
# Set SENTRY_DSN to enable error tracking and performance monitoring
# SENTRY_DSN=https://[email protected]/6789
# Optional Sentry configuration
# SENTRY_TRACES_SAMPLE_RATE=1.0
# SENTRY_SEND_DEFAULT_PII=false
# SENTRY_ENVIRONMENT=production
# SENTRY_RELEASE=1.2.3
# SENTRY_PROFILE_SESSION_SAMPLE_RATE=1.0
# SENTRY_PROFILE_LIFECYCLE=trace
# SENTRY_ENABLE_LOGS=true

# MCP Transport Configuration
# Transport type: 'stdio' (default), 'sse' (Server-Sent Events), or 'http' (HTTP Streamable).
# 'streamable-http' is accepted as an alias for 'http'. Any other value stops the server at startup.
MCP_TRANSPORT=stdio

# HTTP Transport Settings (used when MCP_TRANSPORT=sse or MCP_TRANSPORT=http)
# Host to bind the HTTP server (default: 127.0.0.1)
# MCP_HTTP_HOST=127.0.0.1
# Port to bind the HTTP server (default: 8000)
# MCP_HTTP_PORT=8000
# Optional bearer token for authentication (leave empty for no auth)
# MCP_HTTP_BEARER_TOKEN=

🧰 可用工具

设备与资产清单工具

• devices_list：列出所有设备（可选筛选条件）
• device_get：获取指定设备的详细信息
• device_add：添加新设备
• device_update：更新设备元数据
• device_delete：移除设备
• device_ports：列出设备的所有端口
• device_ports_get：获取设备上指定端口的详细信息
• device_fdb：列出设备的转发数据库（已学习的 MAC 地址）
• device_nac：列出设备上的网络访问控制（802.1X / MAB）会话
• device_availability：获取设备可用性
• device_outages：获取设备中断情况
• device_set_maintenance：设置设备维护模式
• device_discover：使用提供的凭据发现或添加设备
• device_rename：重命名现有设备
• device_maintenance_status：获取设备的维护状态
• device_vlans：列出设备的 VLAN
• device_links：列出设备的链路
• device_wireless_sensors：列出无线传感器（频率、客户端、rssi 等）及其当前值
• device_parents_set：设置设备的依赖父设备（替换当前设置）
• device_parents_clear：移除设备的依赖父设备
• 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_fdb：列出在端口上学习到的 MAC 地址
• 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：从端口组移除端口

端口安全工具

• port_security_list：列出所有设备的端口安全配置
• port_security_device：获取某个设备的端口安全配置
• port_security_port：获取单个端口的端口安全配置

图表工具

图表以 MCP 图片的形式返回。这些工具会向 LibreNMS 请求 PNG 格式，Claude 等 MCP 客户端可以显示该格式（通常无法显示 LibreNMS 默认的 webui.graph_type 格式 SVG）。如果 LibreNMS 版本忽略了该请求，则会改用其 webui.graph_type 格式进行渲染；MIME 类型取自响应。

• device_graphs_list：列出某个设备可用的图表类型
• device_graph：渲染设备级别的图表（例如 device_icmp_perf）
• port_graph：按接口名称渲染端口图表（bits、upkts、nupkts、errors、etherlike；也接受 port_bits 等 LibreNMS 名称）
• port_group_graph：按端口 ID 渲染一个或多个端口的流量图表

包含斜杠（Te2/7）的接口名称会进行百分号编码发送，部分反向代理会拒绝或解码编码后的斜杠。发生这种情况时， port_graph（针对 bits）和 device_ports_get 会改为按端口 ID 重试，因此 在此类代理后仍可正常工作。身份验证错误不会重试；对于不包含斜杠的名称，LibreNMS 自身返回的“未找到”响应会原样报告（包含斜杠的名称始终会重试，因为代理解码后可能会导致 LibreNMS 对错误路径返回“未找到”）。

其他会在路径中使用包含斜杠的值的工具（例如 ports_search、 ports_search_field、使用 0.0.0.0/0 等前缀的 oxidized_config_search、位置名称）没有此类回退机制。如果 LibreNMS 部署在 Apache 后面，请允许编码后的斜杠，以确保所有工具都能正常工作：

AllowEncodedSlashes NoDecode

对于包含编码斜杠的路径，如果 400 或 404 错误并非由 LibreNMS 返回，工具的错误消息中会包含此提示。

告警与日志工具

• 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：编辑告警模板
• 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：删除账单

Oxidized 工具

• oxidized_list：列出由 Oxidized 跟踪、用于配置备份的设备
• oxidized_config_get：获取特定设备的已存储配置
• oxidized_config_search：在所有已存储的设备配置中搜索字符串

网络与监控工具

• 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）条目

• nac_list：列出所有设备上的网络访问控制（802.1X / MAB）会话

• ospf_list：列出 OSPF 实例

• ospf_ports：列出 OSPF 端口

• vrf_list：列出 VRF

• ping：对 LibreNMS 系统执行 Ping

• health_list：列出健康传感器

• health_by_type：按类型列出健康传感器

• health_sensor_get：获取健康传感器的详细信息

• sensors_list：列出传感器

• switching_vlans：列出 LibreNMS 中的所有 VLAN。

• switching_links：列出 LibreNMS 中的所有链路。

• system_info：获取 LibreNMS 的系统信息。

• 支持对所有主要资源（设备、端口、告警、日志、库存等）进行灵活筛选和搜索

📄 分页与数量限制支持

为防止查询大型 LibreNMS 生产实例时超出大模型上下文容量，所有列表、搜索和日志工具均支持分页。

主要功能

• 合理的默认值：所有列表工具默认每页返回 100 条结果。
• 统一参数：
  • limit：要返回的最大结果数（默认值为 100，最小值为 1）。
  • offset（日志工具使用 start）：要跳过的结果数。
• 分页元数据：每个分页响应都包含以下元数据字段：
  • limit：当前生效的数量限制。
  • offset（或 start）：当前生效的偏移量。
  • count：当前页返回的项目数。
  • total：可用项目总数（对于日志工具，若 LibreNMS API 返回此值，则会提供）。

🚨 错误响应

每个返回 JSON 的工具都会使用 LibreNMS 自身的错误格式报告失败， 无论错误来自 LibreNMS、本服务中的检查，还是超时等异常：

{"status": "error", "message": "Device typo does not exist"}

检查 status == "error"。在 1.11.3 及更早版本中，异常会以 {"error": "..."} 的形式返回；检查 error 键的客户端需要更新。

🔒 安全与防护功能

只读模式

本服务支持只读模式，可禁用所有写入操作，以便安全地进行监控：

READ_ONLY_MODE=true

基于标签的工具筛选

你可以通过设置禁用标签来禁用特定类别的工具：

DISABLED_TAGS=alert,alert-rules,alert-templates,bills

当某个工具的任一标签被禁用时，该工具就会隐藏。有些工具带有多个 类别标签：例如，port_graph 带有 graphs 和 ports 标签， 而 ospf_list 带有 routing 和 ospf 标签，因此 DISABLED_TAGS=ports 也会隐藏 port_graph。告警功能分为三个标签：alert（当前告警： 列出、确认、取消静音）、alert-rules 和 alert-templates；禁用这三个标签即可隐藏所有告警工具。

除类别标签外，read-only 用于标记在只读模式下仍可用的工具。admin 和 global-read 标签沿用了较早版本 LibreNMS 为 API 路由设置的权限组 （can:admin、can:global-read）。当前版本的 LibreNMS 会针对每个对象检查权限， 因此应将这两个标签视为宽泛类别，而不是精确对应你的 LibreNMS 用户能够执行的操作。

大型工具集的工具搜索

对于拥有大量工具的服务，FastMCP 工具搜索可以缩短提示词。 启用后，list_tools 会返回两个合成工具：

• search_tools：查找匹配的工具并返回其完整架构
• call_tool：按名称执行任何已发现的工具

启用方法：

TOOL_SEARCH_ENABLED=true
TOOL_SEARCH_STRATEGY=bm25    # bm25 or regex
TOOL_SEARCH_MAX_RESULTS=5    # optional, default is 5

bm25 支持自然语言查询，而 regex 使用正则表达式 pattern 输入进行确定性匹配。

工具搜索遵循现有的可见性控制（只读模式和已禁用的标签）。

速率限制

服务支持速率限制，以控制 API 用量并防止滥用。启用后，会使用滑动窗口算法按客户端限制请求。

在 .env 文件中设置以下环境变量即可启用速率限制：

RATE_LIMIT_ENABLED=true
RATE_LIMIT_MAX_REQUESTS=100   # Maximum requests allowed per window
RATE_LIMIT_WINDOW_MINUTES=1   # Window size in minutes

如果将 RATE_LIMIT_ENABLED 设为 true，服务将启用速率限制中间件。请根据环境需要调整 RATE_LIMIT_MAX_REQUESTS 和 RATE_LIMIT_WINDOW_MINUTES。

Sentry 错误追踪与监控（可选）

服务支持使用 Sentry 进行错误追踪、性能监控和调试。Sentry 集成完全可选，只有在配置后才会初始化。

安装

要启用 Sentry 监控，请安装可选依赖：

# Using UV (recommended)
uv sync --extra sentry

配置

在 .env 文件中设置 SENTRY_DSN 环境变量即可启用 Sentry：

# Required: Sentry DSN for your project
SENTRY_DSN=https://[email protected]/6789

# Optional: Performance monitoring sample rate (0.0-1.0, default: 1.0)
SENTRY_TRACES_SAMPLE_RATE=1.0

# Optional: Include personally identifiable information (default: false).
# When true, tool inputs and outputs (device configs, SNMP credentials) are sent to Sentry.
SENTRY_SEND_DEFAULT_PII=false

# Optional: Environment name (e.g., "production", "staging")
SENTRY_ENVIRONMENT=production

# Optional: Release version (auto-detected from package if not set)
SENTRY_RELEASE=1.2.2

# Optional: Profiling - continuous profiling sample rate (0.0-1.0, default: 1.0)
SENTRY_PROFILE_SESSION_SAMPLE_RATE=1.0

# Optional: Profiling - lifecycle mode for profiling (default: "trace")
# Options: "all", "continuation", "trace"
SENTRY_PROFILE_LIFECYCLE=trace

# Optional: Enable log capture as breadcrumbs and events (default: true)
SENTRY_ENABLE_LOGS=true

功能

启用后，Sentry 会自动捕获：

• 异常与错误：所有未处理异常及其完整上下文
• 性能指标：请求/响应时间和追踪信息
• MCP 集成：详细记录 MCP 服务活动和交互
• 日志与面包屑：用于调试的应用日志和事件轨迹
• 上下文数据：环境、客户端信息和请求参数

获取 Sentry DSN

1. 在 sentry.io 创建免费账户
2. 创建一个新的 Python 项目
3. 从项目设置中复制 DSN
4. 将其设置在 .env 文件中

禁用 Sentry

Sentry 完全可选。如果不设置 SENTRY_DSN，服务将正常运行，不会集成 Sentry，也不会收集任何监控数据。

SSL/TLS 配置

服务支持 SSL 证书验证和自定义超时设置：

LIBRENMS_VERIFY_SSL=true    # Enable SSL certificate verification
LIBRENMS_TIMEOUT=30         # Connection timeout in seconds

传输配置

服务支持多种 MCP 协议传输机制。MCP_TRANSPORT 不区分大小写，streamable-http 可作为 http 的别名；任何其他值都会导致服务在启动时出错并停止，而不会静默回退到 STDIO：

STDIO 传输（默认）

默认传输使用标准输入/输出进行通信。这非常适合本地使用，以及与通过 stdin/stdout 通信的工具集成：

MCP_TRANSPORT=stdio

HTTP SSE 传输（服务器发送事件）

对于基于网络的部署，可以使用 HTTP 搭配服务器发送事件。这允许通过 HTTP 访问 MCP 服务并进行实时流式传输：

MCP_TRANSPORT=sse
MCP_HTTP_HOST=127.0.0.1        # Localhost
MCP_HTTP_PORT=8000           # Port to listen on
MCP_HTTP_BEARER_TOKEN=your-secret-token  # Optional authentication token

使用带有 bearer token 的 SSE 传输时，客户端必须在请求中包含该令牌：

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

HTTP Streamable 传输

HTTP Streamable 传输通过 HTTP 提供基于请求/响应的流式通信。这非常适合 Web 集成和需要 HTTP 端点的工具：

MCP_TRANSPORT=http
MCP_HTTP_HOST=127.0.0.1        # Localhost
MCP_HTTP_PORT=8000           # Port to listen on
MCP_HTTP_BEARER_TOKEN=your-secret-token  # Optional authentication token

使用带有 bearer token 的 Streamable 传输时：

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 传输要求采用正确的 JSON-RPC 格式，并包含 jsonrpc 和 id 字段。某些操作还可能需要服务先初始化会话。

健康检查端点

两种 HTTP 传输方式（sse 和 http）均提供 GET /health。服务器能够处理请求时，该端点会返回 200 ok。此端点无需 bearer token，也不会连接 LibreNMS，因此 LibreNMS 中断不会导致 MCP 服务被标记为不健康。Docker 镜像的 HEALTHCHECK 会使用此端点：

curl http://localhost:8000/health

有关 FastMCP 传输方式的更多信息，请参阅 FastMCP 文档。

🤝 贡献

欢迎贡献。有关开发环境设置、检查和提交消息格式，请参阅 CONTRIBUTING.md；报告错误和功能请求时，请使用问题模板。

发现安全问题？请按照 SECURITY.md 中的说明私下报告。

📜 许可证

MIT 许可证 - 详情请参阅 LICENSE。