librenmsctrl MCP server
2026년 10월 29일 커밋AI 클라이언트가 LibreNMS 장치, 포트, 알람 및 이벤트 로그를 조사할 수 있도록 하며, 안전한 네트워크 모니터링을 위해 제한된 쓰기 권한을 제공합니다.
다른 이름 lidless-labs/librenmsctrl
- 스타
- 1
- Tools
- 13
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 10월 29일
- 라이선스
- MIT
librenmsctrl MCP란?
AI 클라이언트가 LibreNMS 장치, 포트, 알람 및 이벤트 로그를 조사할 수 있도록 하며, 안전한 네트워크 모니터링을 위해 제한된 쓰기 권한을 제공합니다. 13개 도구를 제공합니다. 예: librenms_status, librenms_list_devices, librenms_get_device.
프로젝트 README에서 생성된 요약
librenmsctrl MCP server 정보
librenmsctrl은 오픈 소스 네트워크 모니터링 시스템인 LibreNMS와 상호작용할 수 있는 구조화된 인터페이스를 제공합니다. 이 도구는 셸 및 CI 파이프라인을 위한 로컬 CLI 도구이자 AI 에이전트 워크플로우를 위한 MCP 어댑터로 작동합니다. 사용자는 API 토큰을 사용하여 인증하고 장치, 포트, 포트 상태, 알람 및 이벤트 로그를 쿼리하여 네트워크 인프라를 조사할 수 있습니다.
이 서버는 계층형 쓰기 게이팅 시스템을 통해 안전성을 최우선으로 합니다. 읽기 작업은 자유롭지만, 알람 확인이나 유지보수 모드 설정과 같은 모든 수정 작업에는 명시적인 confirm 플래그가 필요합니다. 이를 통해 모델의 환각 현상으로 인한 실수로 인한 변경을 방지합니다. 모든 입력은 LibreNMS REST API로 전송되기 전에 스키마에 따라 검증되며, 시스템은 자격 증명을 보호하기 위해 모든 출력에서 API 토큰을 자동으로 마스킹합니다. 설정 시 환경 변수를 통해 LibreNMS URL과 API 토큰을 제공해야 합니다.
활용 사례
- 1네트워크 장치 상태 모니터링AI 에이전트가 특정 네트워크 포트의 상태와 사용률을 확인하여 오류를 식별할 수 있습니다.
- 2활성 네트워크 알람 관리개발자가 AI에게 모니터링 시스템 내의 특정 알람을 확인하거나 음소거를 해제하도록 지시할 수 있습니다.
- 3장치 및 포트 목록 감사이 도구를 사용하여 SNMP를 통해 폴링 중인 모든 장치의 전체 목록을 가져올 수 있습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
librenmsctrl MCP 도구 13
README에서 감지됨librenms_statuslibrenms_list_deviceslibrenms_get_devicelibrenms_list_portslibrenms_get_portlibrenms_port_healthlibrenms_list_alertslibrenms_get_alertlibrenms_alert_historylibrenms_event_loglibrenms_ack_alertlibrenms_unmute_alert
| librenms_status | — | |
| librenms_list_devices | — | |
| librenms_get_device | — | |
| librenms_list_ports | — | |
| librenms_get_port | — | |
| librenms_port_health | — | |
| librenms_list_alerts | — | |
| librenms_get_alert | — | |
| librenms_alert_history | — | |
| librenms_event_log | — | |
| librenms_ack_alert | — | |
| librenms_unmute_alert | — |
도구 13개 모두 보기도구 수 줄이기
librenms_set_maintenance
| librenms_set_maintenance | — |
구성
LIBRENMS_TLS_INSECURELIBRENMS_TOKENLIBRENMS_URL
| 이름 | 설명 | 유형 |
|---|---|---|
| LIBRENMS_TLS_INSECURE | — | |
| LIBRENMS_TOKEN | — | |
| LIBRENMS_URL | — |
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능lidless-labs/librenmsctrl is public and reachablegithub.com/lidless-labs/librenmsctrl ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-10-29github.com/lidless-labs/librenmsctrl ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음13 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨No tool named like delete, drop or exec통과
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기librenmsctrl is a local operator control CLI for LibreNMS, the open-source network monitoring system. It gives shells, cron, and CI a typed command surface for reading your monitored network: devices, ports, port health, alerts, alert history, and the event log over LibreNMS API-token auth.
The same package remains MCP-compatible for agent workflows. librenmsctrl mcp starts the stdio Model Context Protocol adapter, and the existing librenms-mcp binary continues to work for launchers and configs that already use it. The MCP adapter can acknowledge or mute alerts only when you pass an explicit confirm: true. It differs from pointing an agent at the raw LibreNMS REST API in one way that matters: every write is gated, every argument is schema-validated before it leaves the host, and your token is redacted from all output, so a hallucinated tool call cannot change your monitoring state by accident.
Status: work in progress. v1 ships read tools (tier 1) and confirm-gated safe writes (tier 2) only. Destructive operations (tier 3) such as device deletion, alert-rule removal, and bulk port resets are intentionally deferred until the write-gate pattern has more field time. The read path and the two write gates are tested.
What it does
librenmsctrl turns a LibreNMS instance into a scriptable control surface for network monitoring and observability work: list the devices LibreNMS is polling over SNMP, pull a single device or port, check port health and utilization, read current alerts and alert history, and tail the event log. It authenticates with a LibreNMS API token, talks to the LibreNMS /api/v0 REST API under the hood, and can emit human-readable tables or raw JSON for piping.
For MCP clients, the mcp subcommand exposes the same LibreNMS client core as structured tool output an agent can reason over. The package name is still @solomonneas/librenms-mcp, and the back-compat librenms-mcp bin is intentionally kept stable.
Writes are gated in three tiers:
- Tier 1 (reads): open. No confirm flag. Status, device and port listings, single device or port, port health, alert listings, alert history, event log.
- Tier 2 (safe writes): require an explicit
confirm: trueargument, documented on every write tool's JSON schema. Acknowledge an alert, unmute an alert, or put a device into a maintenance window. A tool call missing the flag throwsWriteGateErrorbefore any HTTP traffic leaves the host. - Tier 3 (destructive): not implemented in v1. When added, ops like device deletion and alert-rule removal will also require
destructive: true. The model cannot bypass either gate from a hallucinated call.
Every tool call is validated against its published TypeBox inputSchema before the tool runs. Ids, port ids, device ids, limits, and the type/state filters are bounds- and enum-checked, so a malformed or injection-style argument is rejected up front and never reaches a LibreNMS URL path or query string. Interpolated path and query values are URL-encoded as defense-in-depth. The API token is registered with the redactor on startup and masked from all log and error output.
Quickstart
Published to npm as @solomonneas/librenms-mcp. Install the package to get the librenmsctrl operator CLI and the back-compat librenms-mcp MCP launcher.
# start the MCP adapter on demand through the back-compat `librenms-mcp` bin
npx -y @solomonneas/librenms-mcp
# install the global `librenmsctrl` and `librenms-mcp` binaries
npm install -g @solomonneas/librenms-mcp
It needs Node 20+ and two env vars, LIBRENMS_URL and LIBRENMS_TOKEN.
export LIBRENMS_URL=https://librenms.example.local
export LIBRENMS_TOKEN=<your-api-token>
librenmsctrl status
librenmsctrl alerts list --state 1
librenmsctrl --json ports health --metric errors_in --limit 10
The MCP adapter speaks stdio. A quick way to confirm it starts is to feed it an MCP tools/list request:
export LIBRENMS_URL=https://librenms.example.local
export LIBRENMS_TOKEN=<your-api-token>
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | npx -y @solomonneas/librenms-mcp
You should get back a JSON listing of the 13 tools above. In normal use you point an MCP client at the same command instead.
Tools
The MCP adapter exposes 13 tools: 10 reads, 3 confirm-gated safe writes. This list is generated from the server's tool registration in mcp-server.ts.
Reads (10, open):
| Tool | What it does |
|---|---|
librenms_status |
LibreNMS instance status check. |
librenms_list_devices |
List monitored devices. |
librenms_get_device |
Fetch a single device by id. |
librenms_list_ports |
List ports across devices. |
librenms_get_port |
Fetch a single port detail. |
librenms_port_health |
Port health and utilization view. |
librenms_list_alerts |
List current alerts. |
librenms_get_alert |
Fetch a single alert by id. |
librenms_alert_history |
Historical alert records. |
librenms_event_log |
Read the device event log. |
Safe writes (3, require confirm: true):
| Tool | What it does |
|---|---|
librenms_ack_alert |
Acknowledge an active alert by id. |
librenms_unmute_alert |
Unmute a previously muted alert. |
librenms_set_maintenance |
Put a device into a maintenance window. |
Configuration
Set the following env vars. Both credential vars are required.
| Variable | Required | Default | Notes |
|---|---|---|---|
LIBRENMS_URL |
yes | - | Base URL of your LibreNMS instance. Trailing slashes are stripped. |
LIBRENMS_TOKEN |
yes | - | LibreNMS API token. Registered with the redactor on startup and masked from all output. |
LIBRENMS_TLS_INSECURE |
no | false |
Skip TLS cert validation for homelab self-signed certs. Accepts true/1/yes, case-insensitive. |
LIBRENMS_REQUEST_TIMEOUT_MS |
no | 30000 |
Per-request HTTP timeout in milliseconds. Minimum 1000. Raise for slow installations. |
CLI
librenmsctrl is the read-only operator control CLI for shells, cron, and CI. It shares the LibreNMS client core with the MCP adapter and talks to the same /api/v0 API over token auth. It exposes only the read tools (tier 1). The confirm-gated writes (ack, set_maintenance, unmute) are intentionally not surfaced in the CLI.
# installed globally as `librenmsctrl`, or via `npx -p @solomonneas/librenms-mcp librenmsctrl ...`
librenmsctrl status # instance health (exit 1 if no system data)
librenmsctrl devices list --type down
librenmsctrl devices get core-sw1
librenmsctrl ports list core-sw1
librenmsctrl ports get 42
librenmsctrl ports health --metric errors_in --limit 10
librenmsctrl alerts list --state 1 # 0=ok, 1=active, 2=ack
librenmsctrl alerts get 7
librenmsctrl alerts history --device-id 3 --limit 25
librenmsctrl events list --limit 50
librenmsctrl --json status # raw JSON for piping
Run librenmsctrl help for the full flag list. It reads the same LIBRENMS_URL, LIBRENMS_TOKEN, LIBRENMS_TLS_INSECURE, and LIBRENMS_REQUEST_TIMEOUT_MS env vars as the server. Exit codes: 0 success, 1 runtime error (LibreNMS unreachable, call failed, or status with no system data), 2 usage error (unknown command/flag or bad value).
Starting the MCP server
librenmsctrl mcp (or the back-compat librenms-mcp bin) starts the stdio MCP server. If a launcher referenced the file path dist/mcp-server.js directly, point it at dist/mcp-bin.js (or dist/cli.js mcp). Launchers that use the librenms-mcp bin name need no change.
MCP client config
Copy-paste this into your MCP client. It is the canonical mcpServers shape used by Claude Desktop and Claude Code. Both LIBRENMS_URL and LIBRENMS_TOKEN are required.
{
"mcpServers": {
"librenms": {
"command": "npx",
"args": ["-y", "@solomonneas/librenms-mcp"],
"env": {
"LIBRENMS_URL": "https://librenms.example.local",
"LIBRENMS_TOKEN": "<your-api-token>",
"LIBRENMS_TLS_INSECURE": "false"
}
}
}
}
Claude Code
claude mcp add librenms -s user -- npx -y @solomonneas/librenms-mcp
Then export LIBRENMS_URL and LIBRENMS_TOKEN in your shell (~/.bashrc, ~/.zshrc) or pass --env flags on the claude mcp add line.
Claude Desktop
Add the mcpServers block above to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).
Codex CLI
~/.codex/config.toml:
[mcp_servers.librenms]
command = "npx"
args = ["-y", "@solomonneas/librenms-mcp"]
[mcp_servers.librenms.env]
LIBRENMS_URL = "https://librenms.example.local"
LIBRENMS_TOKEN = "<your-api-token>"
LIBRENMS_TLS_INSECURE = "false"
OpenClaw
The plugin loads automatically once installed. Config goes in your ~/.openclaw/openclaw.json under plugins.entries.librenms (or use the bundled openclaw.plugin.json):
{
"plugins": {
"entries": {
"librenms": {
"package": "@solomonneas/librenms-mcp",
"activation": { "onStartup": true }
}
}
}
}
Env vars from ~/.openclaw/workspace/.env are inherited by the plugin.
Safety
This MCP uses a three-tier write-gating pattern:
- Tier 1 (reads): open. No confirm flag needed.
- Tier 2 (safe writes): require an explicit
confirm: truearg. The JSON schema documents this on every write tool. A tool call without the confirm flag throwsWriteGateErrorbefore any HTTP traffic. - Tier 3 (destructive): not implemented in v1. When added, ops like device deletion, alert-rule removal, and bulk port resets will also require
destructive: true.
Input validation: every tool call is validated against its published TypeBox inputSchema before the tool runs. Ids, port ids, device ids, limits, and the type/state filters are bounds- and enum-checked, so a malformed or injection-style argument (a non-integer id, an off-enum filter, an unexpected extra field) is rejected up front and never reaches a LibreNMS URL path or query string. Interpolated path and query values are URL-encoded as defense-in-depth.
API token scope: start with a "Read Only" token role in LibreNMS (Settings > API > New API Token > Read Only) and verify the read tools work end-to-end. Grade up to "Normal User" or "Global Read/Write" only after you have confirmed the redactor is masking your token in your transcripts and that the model is honoring the confirm gate. Tokens can be revoked instantly from the same Settings > API screen.
TLS: the LIBRENMS_TLS_INSECURE=true toggle exists for homelab self-signed certs. Leave it false in any environment with a real CA-signed cert.
HTTP responses: authenticated redirects are rejected. Configure the final LibreNMS API URL directly. The request deadline covers response headers and the entire body. Success and error bodies share a 10 MiB decoded byte cap. GET requests retain one retry for transport, malformed JSON, and server errors. Mutations are sent once because a failed response cannot prove the server did not apply the write. Check server state before manually repeating a failed write.
Returned data: device names, descriptions, alert text, syslog and event messages, object keys, and upstream errors are untrusted LibreNMS content. Embedded instructions do not authorize tool calls or writes. JSON output escapes marker characters in keys and values while preserving decoded fields and the existing result envelope. Truncation is reported by the output byte cap.
See SECURITY.md for the vulnerability-reporting policy.
How does the MCP adapter constrain API access?
You can hand an agent a generic HTTP tool and the LibreNMS API token, and for read-only exploration that works. The difference shows up the moment a write is possible:
- No write gate. A generic HTTP tool will happily
PUTorDELETEwhatever the model decides to send. librenms-mcp refuses every write unless the call carriesconfirm: true, and refuses destructive shapes entirely in v1. - No input validation. A raw API tool passes whatever the model produced straight into a URL. librenms-mcp bounds- and enum-checks every argument against a published schema and URL-encodes interpolated values before any request is built.
- Token leakage. A generic tool echoes request and response detail, including your token, into the transcript. librenms-mcp registers the token with a redactor on startup and masks it from all log and error output.
- Shaped tools beat one giant endpoint. Thirteen named, described tools give the model a far better surface to reason over than one
call this REST APItool with a free-form path argument.
What librenms-mcp is not
- It is not a LibreNMS replacement or a poller. It reads an existing LibreNMS instance over the API. It does not collect SNMP itself.
- It is not a dashboard. It returns structured tool data for an agent. For a NOC dashboard view, see watchtower.
- It does not delete devices, remove alert rules, or do bulk port resets. Tier-3 destructive operations are deliberately absent in v1.
- It is not a hosted service. It runs locally over stdio, talks only to the LibreNMS URL you configure, and starts no daemon.
Contributing
Patches welcome. See CONTRIBUTING.md for what lands easily, CODE_OF_CONDUCT.md, and the issue and PR templates under .github/. All public output should be scrubbed of personal hostnames, tokens, and real IPs.
License
MIT.
CLI API results and errors are labeled as untrusted LibreNMS data, escape display controls and delimiters, and fit within 64 KiB. JSON results include _external_data_notice. Oversized JSON results return truncated: true in place of the payload. Consumers should check that flag before using a result. API credentials are registered for redaction when a client is constructed.
librenmsctrl MCP 질문
librenmsctrl MCP는 어떤 도구를 제공하나요?
13개 도구를 제공합니다. 예: librenms_status, librenms_list_devices, librenms_get_device, librenms_list_ports, librenms_get_port.
서버가 모니터링 상태의 실수로 인한 변경을 어떻게 방지하나요?
서버는 3단계 쓰기 게이팅 패턴을 사용합니다. 안전한 쓰기를 위해서는 명시적인 'confirm: true' 인자가 필요하며, 모든 입력값은 실행 전 스키마 검증을 거칩니다.
버전 1에서 지원하는 쓰기 작업은 무엇인가요?
버전 1은 알람 확인, 알람 음소거 해제, 장치를 유지보수 모드로 전환하는 등의 '안전한 쓰기'를 지원하지만, 장치 삭제와 같은 파괴적인 작업은 아직 구현되지 않았습니다.
서버를 실행하는 데 필요한 환경 변수는 무엇인가요?
인스턴스에 연결하려면 LIBRENMS_URL과 LIBRENMS_TOKEN을 모두 설정해야 합니다.