mcp-librenms 0.1.0__tar.gz

mcp_librenms-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: mcp-librenms
+Version: 0.1.0
+Summary: MCP server that exposes the LibreNMS REST API as MCP tools
+License: MIT
+Keywords: mcp,librenms,monitoring,snmp,network
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pyyaml>=6.0
+
+# mcp-librenms
+
+MCP (Model Context Protocol) server that exposes the [LibreNMS](https://www.librenms.org/) REST API as MCP tools. Built with [FastMCP](https://github.com/jlowin/fastmcp). Connect AI assistants (Claude Desktop, GitHub Copilot, etc.) to your LibreNMS instance to query and manage monitored devices, ports, alerts, logs, and more.
+
+## Features
+
+~40 tools covering:
+
+| Category | Tools |
+|---|---|
+| **System** | `ping`, `system_info` |
+| **Devices** | `list_devices`, `get_device`, `add_device`, `delete_device`, `update_device_field`, `rename_device`, `discover_device`, `get_device_ports`, `get_device_ip_addresses`, `get_device_availability`, `get_device_outages`, `get_device_groups`, `get_device_components`, `get_device_graphs`, `get_device_maintenance`, `set_device_maintenance`, `add_device_eventlog` |
+| **Alerts** | `list_alerts`, `get_alert`, `ack_alert`, `unmute_alert`, `list_alert_rules`, `get_alert_rule`, `delete_alert_rule` |
+| **Ports** | `get_all_ports`, `search_ports`, `get_port_info`, `get_port_ip_info`, `ports_with_mac`, `update_port_description` |
+| **Logs** | `list_eventlog`, `list_syslog`, `list_alertlog`, `list_authlog` |
+| **Locations** | `list_locations`, `get_location`, `add_location`, `delete_location`, `edit_location` |
+| **Sensors** | `list_sensors` |
+| **Device groups** | `list_devicegroups`, `get_devicegroup` |
+| **ARP** | `list_arp` |
+| **Services** | `list_services` |
+| **Inventory** | `get_inventory` |
+
+## Requirements
+
+- Python 3.9+
+- A LibreNMS instance with API access
+- An API token (LibreNMS web UI: **Settings > API > API Settings**)
+
+## Setup
+
+```bash
+# 1. Create and activate a virtual environment
+python -m venv .venv
+.venv\Scripts\activate        # Windows
+source .venv/bin/activate     # Linux/macOS
+
+# 2. Install the package (editable)
+pip install -e .
+
+# 3. Configure
+copy config.example.yaml config.yaml   # Windows
+# cp config.example.yaml config.yaml   # Linux/macOS
+# then edit config.yaml with your LibreNMS URL and API token
+```
+
+### Configuration
+
+`config.yaml` (gitignored — never commit it):
+
+```yaml
+librenms:
+  url: "http://your-librenms-host"   # base URL, no trailing slash
+  token: "your-api-token"            # LibreNMS web UI: Settings > API > API Settings
+```
+
+## Running
+
+The server speaks MCP over **streamable HTTP** by default, bound to `0.0.0.0:5757`:
+
+```bash
+# Console script (foreground)
+mcp-librenms --config config.yaml
+
+# Or as a module
+python -m mcp_librenms --config config.yaml
+```
+
+Endpoint: **http://\<IP\>:5757/mcp**
+
+### Options
+
+| Flag | Default | Description |
+|---|---|---|
+| `--config FILE` | `config.yaml` | Path to YAML config file (CWD, then project root) |
+| `--host IP` | `0.0.0.0` | Bind address |
+| `--port PORT` | `5757` | Bind port |
+| `--daemon` | off | Run in background (detached process) |
+| `--stdio` | off | Use stdio transport instead of HTTP |
+
+Examples:
+
+```bash
+# Background on a custom address/port
+mcp-librenms --config config.yaml --daemon --host 192.168.1.10 --port 8080
+# → http://192.168.1.10:8080/mcp
+
+# stdio transport (for MCP clients that spawn the server)
+mcp-librenms --config config.yaml --stdio
+```
+
+### MCP client configuration
+
+Example for any MCP client that supports streamable HTTP servers:
+
+```json
+{
+  "mcpServers": {
+    "librenms": {
+      "url": "http://your-librenms-host:5757/mcp"
+    }
+  }
+}
+```
+
+For stdio-based clients (Claude Desktop, etc.), spawn the server with `--stdio` and point `--config` at your config file:
+
+```json
+{
+  "mcpServers": {
+    "librenms": {
+      "command": "D:\\path\\to\\.venv\\Scripts\\mcp-librenms.exe",
+      "args": ["--config", "D:\\path\\to\\mcp-librenms\\config.yaml", "--stdio"]
+    }
+  }
+}
+```
+
+> **Note:** the client uses `verify=False` for TLS, so it works with LibreNMS instances behind self-signed certificates.
+
+## Project structure
+
+```
+mcp-librenms/
+├── config.example.yaml   # Template for local configuration
+├── config.yaml           # Your local configuration (gitignored)
+├── .gitignore
+├── README.md
+├── pyproject.toml        # Package metadata + console script
+├── requirements.txt      # Flat dependency list
+└── mcp_librenms/
+    ├── __init__.py
+    ├── __main__.py       # python -m mcp_librenms
+    ├── client.py         # LibreNMS REST API HTTP client
+    └── server.py         # MCP server + tool definitions
+```
+
+## License
+
+MIT

mcp_librenms-0.1.0/README.md

@@ -0,0 +1,139 @@
+# mcp-librenms
+
+MCP (Model Context Protocol) server that exposes the [LibreNMS](https://www.librenms.org/) REST API as MCP tools. Built with [FastMCP](https://github.com/jlowin/fastmcp). Connect AI assistants (Claude Desktop, GitHub Copilot, etc.) to your LibreNMS instance to query and manage monitored devices, ports, alerts, logs, and more.
+
+## Features
+
+~40 tools covering:
+
+| Category | Tools |
+|---|---|
+| **System** | `ping`, `system_info` |
+| **Devices** | `list_devices`, `get_device`, `add_device`, `delete_device`, `update_device_field`, `rename_device`, `discover_device`, `get_device_ports`, `get_device_ip_addresses`, `get_device_availability`, `get_device_outages`, `get_device_groups`, `get_device_components`, `get_device_graphs`, `get_device_maintenance`, `set_device_maintenance`, `add_device_eventlog` |
+| **Alerts** | `list_alerts`, `get_alert`, `ack_alert`, `unmute_alert`, `list_alert_rules`, `get_alert_rule`, `delete_alert_rule` |
+| **Ports** | `get_all_ports`, `search_ports`, `get_port_info`, `get_port_ip_info`, `ports_with_mac`, `update_port_description` |
+| **Logs** | `list_eventlog`, `list_syslog`, `list_alertlog`, `list_authlog` |
+| **Locations** | `list_locations`, `get_location`, `add_location`, `delete_location`, `edit_location` |
+| **Sensors** | `list_sensors` |
+| **Device groups** | `list_devicegroups`, `get_devicegroup` |
+| **ARP** | `list_arp` |
+| **Services** | `list_services` |
+| **Inventory** | `get_inventory` |
+
+## Requirements
+
+- Python 3.9+
+- A LibreNMS instance with API access
+- An API token (LibreNMS web UI: **Settings > API > API Settings**)
+
+## Setup
+
+```bash
+# 1. Create and activate a virtual environment
+python -m venv .venv
+.venv\Scripts\activate        # Windows
+source .venv/bin/activate     # Linux/macOS
+
+# 2. Install the package (editable)
+pip install -e .
+
+# 3. Configure
+copy config.example.yaml config.yaml   # Windows
+# cp config.example.yaml config.yaml   # Linux/macOS
+# then edit config.yaml with your LibreNMS URL and API token
+```
+
+### Configuration
+
+`config.yaml` (gitignored — never commit it):
+
+```yaml
+librenms:
+  url: "http://your-librenms-host"   # base URL, no trailing slash
+  token: "your-api-token"            # LibreNMS web UI: Settings > API > API Settings
+```
+
+## Running
+
+The server speaks MCP over **streamable HTTP** by default, bound to `0.0.0.0:5757`:
+
+```bash
+# Console script (foreground)
+mcp-librenms --config config.yaml
+
+# Or as a module
+python -m mcp_librenms --config config.yaml
+```
+
+Endpoint: **http://\<IP\>:5757/mcp**
+
+### Options
+
+| Flag | Default | Description |
+|---|---|---|
+| `--config FILE` | `config.yaml` | Path to YAML config file (CWD, then project root) |
+| `--host IP` | `0.0.0.0` | Bind address |
+| `--port PORT` | `5757` | Bind port |
+| `--daemon` | off | Run in background (detached process) |
+| `--stdio` | off | Use stdio transport instead of HTTP |
+
+Examples:
+
+```bash
+# Background on a custom address/port
+mcp-librenms --config config.yaml --daemon --host 192.168.1.10 --port 8080
+# → http://192.168.1.10:8080/mcp
+
+# stdio transport (for MCP clients that spawn the server)
+mcp-librenms --config config.yaml --stdio
+```
+
+### MCP client configuration
+
+Example for any MCP client that supports streamable HTTP servers:
+
+```json
+{
+  "mcpServers": {
+    "librenms": {
+      "url": "http://your-librenms-host:5757/mcp"
+    }
+  }
+}
+```
+
+For stdio-based clients (Claude Desktop, etc.), spawn the server with `--stdio` and point `--config` at your config file:
+
+```json
+{
+  "mcpServers": {
+    "librenms": {
+      "command": "D:\\path\\to\\.venv\\Scripts\\mcp-librenms.exe",
+      "args": ["--config", "D:\\path\\to\\mcp-librenms\\config.yaml", "--stdio"]
+    }
+  }
+}
+```
+
+> **Note:** the client uses `verify=False` for TLS, so it works with LibreNMS instances behind self-signed certificates.
+
+## Project structure
+
+```
+mcp-librenms/
+├── config.example.yaml   # Template for local configuration
+├── config.yaml           # Your local configuration (gitignored)
+├── .gitignore
+├── README.md
+├── pyproject.toml        # Package metadata + console script
+├── requirements.txt      # Flat dependency list
+└── mcp_librenms/
+    ├── __init__.py
+    ├── __main__.py       # python -m mcp_librenms
+    ├── client.py         # LibreNMS REST API HTTP client
+    └── server.py         # MCP server + tool definitions
+```
+
+## License
+
+MIT

mcp_librenms-0.1.0/mcp_librenms/__init__.py

@@ -0,0 +1,3 @@
+"""mcp-librenms — MCP server exposing the LibreNMS API as MCP tools."""
+
+__version__ = "0.1.0"

mcp_librenms-0.1.0/mcp_librenms/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running the server with `python -m mcp_librenms`."""
+
+from mcp_librenms.server import run
+
+if __name__ == "__main__":
+    run()

mcp_librenms-0.1.0/mcp_librenms/client.py

@@ -0,0 +1,211 @@
+"""LibreNMS API HTTP client."""
+
+import httpx
+from typing import Any, Optional
+
+
+class LibreNMSClient:
+    def __init__(self, base_url: str, token: str):
+        if not base_url or not token:
+            raise ValueError(
+                "LibreNMS base_url and token are required "
+                "(set them in the config file, see config.example.yaml)"
+            )
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.api_base = f"{self.base_url}/api/v0"
+        self.headers = {"X-Auth-Token": self.token, "Content-Type": "application/json"}
+
+    def _get(self, path: str, params: Optional[dict] = None) -> dict:
+        url = f"{self.api_base}{path}"
+        with httpx.Client(verify=False, timeout=30) as client:
+            resp = client.get(url, headers=self.headers, params=params)
+            resp.raise_for_status()
+            return resp.json()
+
+    def _post(self, path: str, data: Optional[dict] = None) -> dict:
+        url = f"{self.api_base}{path}"
+        with httpx.Client(verify=False, timeout=30) as client:
+            resp = client.post(url, headers=self.headers, json=data or {})
+            resp.raise_for_status()
+            return resp.json()
+
+    def _put(self, path: str, data: Optional[dict] = None) -> dict:
+        url = f"{self.api_base}{path}"
+        with httpx.Client(verify=False, timeout=30) as client:
+            resp = client.put(url, headers=self.headers, json=data or {})
+            resp.raise_for_status()
+            return resp.json()
+
+    def _patch(self, path: str, data: Optional[dict] = None) -> dict:
+        url = f"{self.api_base}{path}"
+        with httpx.Client(verify=False, timeout=30) as client:
+            resp = client.patch(url, headers=self.headers, json=data or {})
+            resp.raise_for_status()
+            return resp.json()
+
+    def _delete(self, path: str) -> dict:
+        url = f"{self.api_base}{path}"
+        with httpx.Client(verify=False, timeout=30) as client:
+            resp = client.delete(url, headers=self.headers)
+            resp.raise_for_status()
+            return resp.json()
+
+    # ── System ────────────────────────────────────────────────────────────────
+    def ping(self) -> dict:
+        return self._get("/ping")
+
+    def system_info(self) -> dict:
+        return self._get("/system")
+
+    # ── Devices ───────────────────────────────────────────────────────────────
+    def list_devices(self, **params) -> dict:
+        return self._get("/devices", params=params or None)
+
+    def get_device(self, hostname: str) -> dict:
+        return self._get(f"/devices/{hostname}")
+
+    def add_device(self, data: dict) -> dict:
+        return self._post("/devices", data)
+
+    def delete_device(self, hostname: str) -> dict:
+        return self._delete(f"/devices/{hostname}")
+
+    def update_device_field(self, hostname: str, field: str, data: dict) -> dict:
+        return self._patch(f"/devices/{hostname}", {"field": field, **data})
+
+    def rename_device(self, hostname: str, new_hostname: str) -> dict:
+        return self._patch(f"/devices/{hostname}/rename/{new_hostname}")
+
+    def discover_device(self, hostname: str) -> dict:
+        return self._get(f"/devices/{hostname}/discover")
+
+    def get_device_ports(self, hostname: str, **params) -> dict:
+        return self._get(f"/devices/{hostname}/ports", params=params or None)
+
+    def get_device_ip_addresses(self, hostname: str) -> dict:
+        return self._get(f"/devices/{hostname}/ip")
+
+    def get_device_availability(self, hostname: str) -> dict:
+        return self._get(f"/devices/{hostname}/availability")
+
+    def get_device_outages(self, hostname: str) -> dict:
+        return self._get(f"/devices/{hostname}/outages")
+
+    def get_device_groups(self, hostname: str) -> dict:
+        return self._get(f"/devices/{hostname}/groups")
+
+    def get_device_graphs(self, hostname: str) -> dict:
+        return self._get(f"/devices/{hostname}/graphs")
+
+    def get_device_components(self, hostname: str) -> dict:
+        return self._get(f"/devices/{hostname}/components")
+
+    def get_device_maintenance(self, hostname: str) -> dict:
+        return self._get(f"/devices/{hostname}/maintenance")
+
+    def set_device_maintenance(self, hostname: str, data: dict) -> dict:
+        return self._post(f"/devices/{hostname}/maintenance", data)
+
+    def add_device_eventlog(self, hostname: str, text: str, severity: str = "2") -> dict:
+        return self._post(f"/devices/{hostname}/eventlog", {"text": text, "severity": severity})
+
+    # ── Alerts ────────────────────────────────────────────────────────────────
+    def list_alerts(self, **params) -> dict:
+        return self._get("/alerts", params=params or None)
+
+    def get_alert(self, alert_id: int) -> dict:
+        return self._get(f"/alerts/{alert_id}")
+
+    def ack_alert(self, alert_id: int) -> dict:
+        return self._put(f"/alerts/{alert_id}")
+
+    def unmute_alert(self, alert_id: int) -> dict:
+        return self._put(f"/alerts/unmute/{alert_id}")
+
+    def list_alert_rules(self) -> dict:
+        return self._get("/rules")
+
+    def get_alert_rule(self, rule_id: int) -> dict:
+        return self._get(f"/rules/{rule_id}")
+
+    def delete_alert_rule(self, rule_id: int) -> dict:
+        return self._delete(f"/rules/{rule_id}")
+
+    # ── Ports ─────────────────────────────────────────────────────────────────
+    def get_all_ports(self, columns: Optional[str] = None) -> dict:
+        params = {"columns": columns} if columns else None
+        return self._get("/ports", params=params)
+
+    def search_ports(self, field: str, search: str, columns: Optional[str] = None) -> dict:
+        params = {"columns": columns} if columns else None
+        return self._get(f"/ports/search/{field}/{search}", params=params)
+
+    def get_port_info(self, port_id: int) -> dict:
+        return self._get(f"/ports/{port_id}")
+
+    def get_port_ip_info(self, port_id: int) -> dict:
+        return self._get(f"/ports/{port_id}/ip")
+
+    def ports_with_mac(self, mac: str) -> dict:
+        return self._get(f"/ports/mac/{mac}")
+
+    def update_port_description(self, port_id: int, description: str) -> dict:
+        return self._patch(f"/ports/{port_id}/description", {"description": description})
+
+    # ── Logs ──────────────────────────────────────────────────────────────────
+    def list_eventlog(self, hostname: Optional[str] = None, **params) -> dict:
+        path = f"/logs/eventlog/{hostname}" if hostname else "/logs/eventlog"
+        return self._get(path, params=params or None)
+
+    def list_syslog(self, hostname: Optional[str] = None, **params) -> dict:
+        path = f"/logs/syslog/{hostname}" if hostname else "/logs/syslog"
+        return self._get(path, params=params or None)
+
+    def list_alertlog(self, hostname: Optional[str] = None, **params) -> dict:
+        path = f"/logs/alertlog/{hostname}" if hostname else "/logs/alertlog"
+        return self._get(path, params=params or None)
+
+    def list_authlog(self, **params) -> dict:
+        return self._get("/logs/authlog", params=params or None)
+
+    # ── Locations ─────────────────────────────────────────────────────────────
+    def list_locations(self) -> dict:
+        return self._get("/resources/locations")
+
+    def get_location(self, location: str) -> dict:
+        return self._get(f"/location/{location}")
+
+    def add_location(self, data: dict) -> dict:
+        return self._post("/locations", data)
+
+    def delete_location(self, location: str) -> dict:
+        return self._delete(f"/locations/{location}")
+
+    def edit_location(self, location: str, data: dict) -> dict:
+        return self._patch(f"/locations/{location}", data)
+
+    # ── Sensors ───────────────────────────────────────────────────────────────
+    def list_sensors(self) -> dict:
+        return self._get("/resources/sensors")
+
+    # ── Device Groups ─────────────────────────────────────────────────────────
+    def list_devicegroups(self) -> dict:
+        return self._get("/devicegroups")
+
+    def get_devicegroup(self, name: str) -> dict:
+        return self._get(f"/devicegroups/{name}")
+
+    # ── ARP ───────────────────────────────────────────────────────────────────
+    def list_arp(self, query: str, **params) -> dict:
+        return self._get(f"/resources/ip/arp/{query}", params=params or None)
+
+    # ── Services ──────────────────────────────────────────────────────────────
+    def list_services(self, hostname: Optional[str] = None) -> dict:
+        if hostname:
+            return self._get(f"/services/{hostname}")
+        return self._get("/services")
+
+    # ── Inventory ─────────────────────────────────────────────────────────────
+    def get_inventory(self, hostname: str, **params) -> dict:
+        return self._get(f"/inventory/{hostname}", params=params or None)

mcp_librenms-0.1.0/mcp_librenms/server.py

@@ -0,0 +1,582 @@
+"""LibreNMS MCP Server — exposes LibreNMS API operations as MCP tools (FastMCP)."""
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional
+
+import yaml
+from fastmcp import FastMCP
+
+mcp = FastMCP("librenms-mcp")
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+
+# Lazy-initialised client so the config is loaded before the first tool call
+_client = None
+_config: dict = {}
+
+
+def _resolve_config(path: str) -> Path:
+    """Resolve a (possibly relative) config path: CWD first, then project root."""
+    p = Path(path)
+    if not p.is_absolute():
+        cwd_candidate = Path.cwd() / p
+        if cwd_candidate.exists():
+            return cwd_candidate
+        return PROJECT_ROOT / p
+    return p
+
+
+def load_config(path: str) -> dict:
+    """Load and validate the YAML config file."""
+    p = _resolve_config(path)
+    if not p.exists():
+        raise FileNotFoundError(
+            f"Config file not found: {p} "
+            f"(copy config.example.yaml to config.yaml and fill in your values)"
+        )
+    with open(p, "r", encoding="utf-8") as f:
+        data = yaml.safe_load(f) or {}
+    lib = data.get("librenms") or {}
+    url = str(lib.get("url") or "").strip()
+    token = str(lib.get("token") or "").strip()
+    if not url or not token:
+        raise ValueError(
+            f"Config file {p} must define non-empty librenms.url and librenms.token"
+        )
+    return {"url": url, "token": token}
+
+
+def client():
+    global _client
+    if _client is None:
+        from mcp_librenms.client import LibreNMSClient
+        _client = LibreNMSClient(_config["url"], _config["token"])
+    return _client
+
+
+def _json(data) -> str:
+    return json.dumps(data, indent=2, ensure_ascii=False)
+
+
+# ── System ────────────────────────────────────────────────────────────────────
+
+@mcp.tool
+def ping() -> str:
+    """Check LibreNMS API availability. Sends exactly 3 ping requests (not continuous)
+    and reports the result of each."""
+    c = client()
+    results = []
+    for i in range(1, 4):
+        try:
+            results.append({"ping": i, "status": "ok", "response": c.ping()})
+        except Exception as e:
+            results.append({"ping": i, "status": "fail", "error": str(e)})
+    return _json({
+        "pings": results,
+        "success": sum(1 for r in results if r["status"] == "ok"),
+        "total": len(results),
+    })
+
+
+@mcp.tool
+def system_info() -> str:
+    """Display LibreNMS instance information (version, PHP, DB, RRDtool, etc.)."""
+    return _json(client().system_info())
+
+
+# ── Devices ───────────────────────────────────────────────────────────────────
+
+@mcp.tool
+def list_devices(
+    type: Optional[str] = None,
+    os: Optional[str] = None,
+    mac: Optional[str] = None,
+    ipv4: Optional[str] = None,
+    ipv6: Optional[str] = None,
+    hostname: Optional[str] = None,
+    sysName: Optional[str] = None,
+    location: Optional[str] = None,
+    status: Optional[int] = None,
+) -> str:
+    """List all devices monitored by LibreNMS.
+
+    Optional filters: type (router/switch/etc.), os, mac, ipv4, ipv6, hostname,
+    sysName, location, status (0=down, 1=up).
+    """
+    params = {
+        "type": type, "os": os, "mac": mac, "ipv4": ipv4, "ipv6": ipv6,
+        "hostname": hostname, "sysName": sysName, "location": location,
+        "status": status,
+    }
+    return _json(client().list_devices(**{k: v for k, v in params.items() if v is not None}))
+
+
+@mcp.tool
+def get_device(hostname: str) -> str:
+    """Get detailed information about a specific device by hostname or device ID."""
+    return _json(client().get_device(hostname))
+
+
+@mcp.tool
+def add_device(
+    hostname: str,
+    snmpver: Optional[str] = None,
+    community: Optional[str] = None,
+    port: Optional[int] = None,
+    transport: Optional[str] = None,
+    authlevel: Optional[str] = None,
+    authname: Optional[str] = None,
+    authpass: Optional[str] = None,
+    authalgo: Optional[str] = None,
+    cryptopass: Optional[str] = None,
+    cryptoalgo: Optional[str] = None,
+    force_add: Optional[bool] = None,
+) -> str:
+    """Add a new device to LibreNMS monitoring.
+
+    Required: hostname. Common optional fields: snmpver (v1/v2c/v3), community
+    (SNMPv1/v2c), authlevel, authname, authpass, authalgo, cryptopass, cryptoalgo
+    (SNMPv3), port, transport (udp/tcp/udp6/tcp6), force_add.
+    """
+    data = {
+        "hostname": hostname, "snmpver": snmpver, "community": community,
+        "port": port, "transport": transport, "authlevel": authlevel,
+        "authname": authname, "authpass": authpass, "authalgo": authalgo,
+        "cryptopass": cryptopass, "cryptoalgo": cryptoalgo, "force_add": force_add,
+    }
+    return _json(client().add_device({k: v for k, v in data.items() if v is not None}))
+
+
+@mcp.tool
+def delete_device(hostname: str) -> str:
+    """Remove a device from LibreNMS monitoring."""
+    return _json(client().delete_device(hostname))
+
+
+@mcp.tool
+def update_device_field(hostname: str, field: str, data: dict) -> str:
+    """Update a field on a device (e.g. location, notes, ignore, disable, etc.)."""
+    return _json(client().update_device_field(hostname, field, data))
+
+
+@mcp.tool
+def rename_device(hostname: str, new_hostname: str) -> str:
+    """Rename a device to a new hostname."""
+    return _json(client().rename_device(hostname, new_hostname))
+
+
+@mcp.tool
+def discover_device(hostname: str) -> str:
+    """Trigger immediate SNMP discovery for a device."""
+    return _json(client().discover_device(hostname))
+
+
+@mcp.tool
+def get_device_ports(hostname: str, columns: Optional[str] = None) -> str:
+    """List all network ports/interfaces for a device.
+
+    Optional: columns — comma-separated column names to return.
+    """
+    params = {"columns": columns} if columns else {}
+    return _json(client().get_device_ports(hostname, **params))
+
+
+@mcp.tool
+def get_device_ip_addresses(hostname: str) -> str:
+    """Get all IP addresses (v4 and v6) assigned to a device."""
+    return _json(client().get_device_ip_addresses(hostname))
+
+
+@mcp.tool
+def get_device_availability(hostname: str) -> str:
+    """Get uptime/availability statistics for a device."""
+    return _json(client().get_device_availability(hostname))
+
+
+@mcp.tool
+def get_device_outages(hostname: str) -> str:
+    """Get outage history for a device."""
+    return _json(client().get_device_outages(hostname))
+
+
+@mcp.tool
+def get_device_groups(hostname: str) -> str:
+    """List device groups that a specific device belongs to."""
+    return _json(client().get_device_groups(hostname))
+
+
+@mcp.tool
+def get_device_components(hostname: str) -> str:
+    """List hardware/software components discovered on a device."""
+    return _json(client().get_device_components(hostname))
+
+
+@mcp.tool
+def get_device_graphs(hostname: str) -> str:
+    """List available graphs for a device."""
+    return _json(client().get_device_graphs(hostname))
+
+
+@mcp.tool
+def get_device_maintenance(hostname: str) -> str:
+    """Get current maintenance schedule status for a device."""
+    return _json(client().get_device_maintenance(hostname))
+
+
+@mcp.tool
+def set_device_maintenance(
+    hostname: str,
+    duration: str,
+    title: Optional[str] = None,
+    notes: Optional[str] = None,
+    start: Optional[str] = None,
+) -> str:
+    """Put a device into maintenance mode.
+
+    Required: duration (format H:i e.g. '02:00').
+    Optional: title, notes, start (format 'Y-m-d H:i:00').
+    """
+    data = {"duration": duration}
+    for key, value in (("title", title), ("notes", notes), ("start", start)):
+        if value is not None:
+            data[key] = value
+    return _json(client().set_device_maintenance(hostname, data))
+
+
+@mcp.tool
+def add_device_eventlog(hostname: str, text: str, severity: str = "2") -> str:
+    """Add a custom event log entry for a device.
+
+    Severity: 1=ok, 2=info, 3=notice, 4=warning, 5=error.
+    """
+    return _json(client().add_device_eventlog(hostname, text, severity))
+
+
+# ── Alerts ────────────────────────────────────────────────────────────────────
+
+@mcp.tool
+def list_alerts(
+    state: Optional[int] = None,
+    severity: Optional[str] = None,
+    alert_rule_id: Optional[int] = None,
+) -> str:
+    """List all alerts.
+
+    Optional filters: state (0=ok, 1=alert, 2=acknowledged),
+    severity (ok/warning/critical), alert_rule_id.
+    """
+    params = {
+        "state": state, "severity": severity, "alert_rule_id": alert_rule_id,
+    }
+    return _json(client().list_alerts(**{k: v for k, v in params.items() if v is not None}))
+
+
+@mcp.tool
+def get_alert(alert_id: int) -> str:
+    """Get details for a specific alert by ID."""
+    return _json(client().get_alert(alert_id))
+
+
+@mcp.tool
+def ack_alert(alert_id: int) -> str:
+    """Acknowledge an active alert to suppress further notifications."""
+    return _json(client().ack_alert(alert_id))
+
+
+@mcp.tool
+def unmute_alert(alert_id: int) -> str:
+    """Unmute a muted/acknowledged alert so it can fire again."""
+    return _json(client().unmute_alert(alert_id))
+
+
+@mcp.tool
+def list_alert_rules() -> str:
+    """List all configured alert rules."""
+    return _json(client().list_alert_rules())
+
+
+@mcp.tool
+def get_alert_rule(rule_id: int) -> str:
+    """Get details for a specific alert rule by ID."""
+    return _json(client().get_alert_rule(rule_id))
+
+
+@mcp.tool
+def delete_alert_rule(rule_id: int) -> str:
+    """Delete an alert rule by ID."""
+    return _json(client().delete_alert_rule(rule_id))
+
+
+# ── Ports ─────────────────────────────────────────────────────────────────────
+
+@mcp.tool
+def get_all_ports(columns: Optional[str] = None) -> str:
+    """Get info for all ports across all devices.
+
+    Use 'columns' to limit returned fields, e.g. 'ifName,port_id,device_id'.
+    """
+    return _json(client().get_all_ports(columns))
+
+
+@mcp.tool
+def search_ports(field: str, search: str, columns: Optional[str] = None) -> str:
+    """Search for ports matching a string across specified fields.
+
+    field: comma-separated field(s) to search, e.g. 'ifAlias,ifDescr,ifName'.
+    """
+    return _json(client().search_ports(field, search, columns))
+
+
+@mcp.tool
+def get_port_info(port_id: int) -> str:
+    """Get all information for a specific port by port ID."""
+    return _json(client().get_port_info(port_id))
+
+
+@mcp.tool
+def get_port_ip_info(port_id: int) -> str:
+    """Get all IP addresses (v4 and v6) for a specific port by port ID."""
+    return _json(client().get_port_ip_info(port_id))
+
+
+@mcp.tool
+def ports_with_mac(mac: str) -> str:
+    """Find ports associated with a specific MAC address (various formats accepted)."""
+    return _json(client().ports_with_mac(mac))
+
+
+@mcp.tool
+def update_port_description(port_id: int, description: str) -> str:
+    """Update the ifAlias/description for a port. Send empty string to reset to default."""
+    return _json(client().update_port_description(port_id, description))
+
+
+# ── Logs ──────────────────────────────────────────────────────────────────────
+
+@mcp.tool
+def list_eventlog(
+    hostname: Optional[str] = None,
+    start: Optional[int] = None,
+    limit: Optional[int] = None,
+    from_: Optional[str] = None,
+    to: Optional[str] = None,
+    sortorder: Optional[str] = None,
+) -> str:
+    """List event log entries.
+
+    Optional: hostname to filter by device. Params: start (page), limit,
+    from_ (start datetime or event_id), to, sortorder (ASC/DESC).
+    """
+    params = {
+        "start": start, "limit": limit, "from": from_, "to": to,
+        "sortorder": sortorder,
+    }
+    return _json(client().list_eventlog(hostname, **{k: v for k, v in params.items() if v is not None}))
+
+
+@mcp.tool
+def list_syslog(
+    hostname: Optional[str] = None,
+    start: Optional[int] = None,
+    limit: Optional[int] = None,
+    from_: Optional[str] = None,
+    to: Optional[str] = None,
+    sortorder: Optional[str] = None,
+) -> str:
+    """List syslog entries.
+
+    Optional: hostname to filter by device. Supports same params as list_eventlog.
+    """
+    params = {
+        "start": start, "limit": limit, "from": from_, "to": to,
+        "sortorder": sortorder,
+    }
+    return _json(client().list_syslog(hostname, **{k: v for k, v in params.items() if v is not None}))
+
+
+@mcp.tool
+def list_alertlog(
+    hostname: Optional[str] = None,
+    start: Optional[int] = None,
+    limit: Optional[int] = None,
+    from_: Optional[str] = None,
+    to: Optional[str] = None,
+) -> str:
+    """List alert log entries. Optional: hostname to filter by device."""
+    params = {"start": start, "limit": limit, "from": from_, "to": to}
+    return _json(client().list_alertlog(hostname, **{k: v for k, v in params.items() if v is not None}))
+
+
+@mcp.tool
+def list_authlog(start: Optional[int] = None, limit: Optional[int] = None) -> str:
+    """List authentication log entries."""
+    params = {"start": start, "limit": limit}
+    return _json(client().list_authlog(**{k: v for k, v in params.items() if v is not None}))
+
+
+# ── Locations ─────────────────────────────────────────────────────────────────
+
+@mcp.tool
+def list_locations() -> str:
+    """List all configured locations with coordinates."""
+    return _json(client().list_locations())
+
+
+@mcp.tool
+def get_location(location: str) -> str:
+    """Get details for a specific location by name or ID."""
+    return _json(client().get_location(location))
+
+
+@mcp.tool
+def add_location(
+    location: str,
+    lat: Optional[str] = None,
+    lng: Optional[str] = None,
+    fixed_coordinates: Optional[int] = None,
+) -> str:
+    """Add a new location with coordinates.
+
+    fixed_coordinates: 1=fixed, 0=auto-update from device.
+    """
+    data = {
+        "location": location, "lat": lat, "lng": lng,
+        "fixed_coordinates": fixed_coordinates,
+    }
+    return _json(client().add_location({k: v for k, v in data.items() if v is not None}))
+
+
+@mcp.tool
+def delete_location(location: str) -> str:
+    """Delete a location by name or ID."""
+    return _json(client().delete_location(location))
+
+
+@mcp.tool
+def edit_location(
+    location: str,
+    lat: Optional[str] = None,
+    lng: Optional[str] = None,
+) -> str:
+    """Edit a location's coordinates."""
+    data = {"lat": lat, "lng": lng}
+    return _json(client().edit_location(location, {k: v for k, v in data.items() if v is not None}))
+
+
+# ── Sensors ───────────────────────────────────────────────────────────────────
+
+@mcp.tool
+def list_sensors() -> str:
+    """List all sensors discovered across all devices (temperature, humidity, voltage, etc.)."""
+    return _json(client().list_sensors())
+
+
+# ── Device Groups ─────────────────────────────────────────────────────────────
+
+@mcp.tool
+def list_devicegroups() -> str:
+    """List all device groups."""
+    return _json(client().list_devicegroups())
+
+
+@mcp.tool
+def get_devicegroup(name: str) -> str:
+    """Get devices belonging to a specific device group."""
+    return _json(client().get_devicegroup(name))
+
+
+# ── ARP ───────────────────────────────────────────────────────────────────────
+
+@mcp.tool
+def list_arp(query: str, device: Optional[str] = None) -> str:
+    """Look up ARP table entries by IP address, MAC address or CIDR range.
+
+    Optional: device to filter by device hostname.
+    """
+    params = {"device": device} if device else {}
+    return _json(client().list_arp(query, **params))
+
+
+# ── Services ──────────────────────────────────────────────────────────────────
+
+@mcp.tool
+def list_services(hostname: Optional[str] = None) -> str:
+    """List Nagios-compatible service checks. Optional: filter by device hostname."""
+    return _json(client().list_services(hostname))
+
+
+# ── Inventory ─────────────────────────────────────────────────────────────────
+
+@mcp.tool
+def get_inventory(hostname: str, entPhysicalClass: Optional[str] = None) -> str:
+    """Get hardware inventory (modules, cards, chassis) for a device.
+
+    Optional: entPhysicalClass to filter by physical class.
+    """
+    params = {"entPhysicalClass": entPhysicalClass} if entPhysicalClass else {}
+    return _json(client().get_inventory(hostname, **params))
+
+
+def _spawn_daemon(args: argparse.Namespace) -> None:
+    """Re-launch this server as a detached background process."""
+    cmd = [sys.executable, "-m", "mcp_librenms",
+           "--config", str(_resolve_config(args.config)),
+           "--host", args.host, "--port", str(args.port)]
+    kwargs = dict(
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        stdin=subprocess.DEVNULL,
+        cwd=str(Path(__file__).resolve().parent.parent),
+    )
+    if os.name == "nt":
+        # DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP
+        kwargs["creationflags"] = 0x00000008 | 0x00000200
+    else:
+        kwargs["start_new_session"] = True
+    proc = subprocess.Popen(cmd, **kwargs)
+    print(f"mcp-librenms started in background (PID {proc.pid})")
+    print(f"Endpoint: http://{args.host}:{args.port}/mcp")
+
+
+def run():
+    """Console-script entry point.
+
+    Default: HTTP transport on 0.0.0.0:5757 (endpoint http://<ip>:5757/mcp).
+    Options: --config (YAML config), --daemon (background), --host, --port, --stdio.
+    """
+    parser = argparse.ArgumentParser(description="LibreNMS MCP server (FastMCP)")
+    parser.add_argument("--config", default="config.yaml",
+                        help="path to YAML config file (default: config.yaml)")
+    parser.add_argument("--daemon", action="store_true",
+                        help="run in background (detached process)")
+    parser.add_argument("--host", default="0.0.0.0",
+                        help="bind address (default: 0.0.0.0)")
+    parser.add_argument("--port", type=int, default=5757,
+                        help="bind port (default: 5757)")
+    parser.add_argument("--stdio", action="store_true",
+                        help="use stdio transport instead of HTTP")
+    args = parser.parse_args()
+
+    global _config
+    try:
+        _config = load_config(args.config)
+    except (FileNotFoundError, ValueError) as e:
+        parser.error(str(e))
+
+    if args.daemon:
+        _spawn_daemon(args)
+        return
+
+    if args.stdio:
+        mcp.run(transport="stdio")
+    else:
+        mcp.run(transport="http", host=args.host, port=args.port)
+
+
+if __name__ == "__main__":
+    run()

mcp_librenms-0.1.0/mcp_librenms.egg-info/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: mcp-librenms
+Version: 0.1.0
+Summary: MCP server that exposes the LibreNMS REST API as MCP tools
+License: MIT
+Keywords: mcp,librenms,monitoring,snmp,network
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pyyaml>=6.0
+
+# mcp-librenms
+
+MCP (Model Context Protocol) server that exposes the [LibreNMS](https://www.librenms.org/) REST API as MCP tools. Built with [FastMCP](https://github.com/jlowin/fastmcp). Connect AI assistants (Claude Desktop, GitHub Copilot, etc.) to your LibreNMS instance to query and manage monitored devices, ports, alerts, logs, and more.
+
+## Features
+
+~40 tools covering:
+
+| Category | Tools |
+|---|---|
+| **System** | `ping`, `system_info` |
+| **Devices** | `list_devices`, `get_device`, `add_device`, `delete_device`, `update_device_field`, `rename_device`, `discover_device`, `get_device_ports`, `get_device_ip_addresses`, `get_device_availability`, `get_device_outages`, `get_device_groups`, `get_device_components`, `get_device_graphs`, `get_device_maintenance`, `set_device_maintenance`, `add_device_eventlog` |
+| **Alerts** | `list_alerts`, `get_alert`, `ack_alert`, `unmute_alert`, `list_alert_rules`, `get_alert_rule`, `delete_alert_rule` |
+| **Ports** | `get_all_ports`, `search_ports`, `get_port_info`, `get_port_ip_info`, `ports_with_mac`, `update_port_description` |
+| **Logs** | `list_eventlog`, `list_syslog`, `list_alertlog`, `list_authlog` |
+| **Locations** | `list_locations`, `get_location`, `add_location`, `delete_location`, `edit_location` |
+| **Sensors** | `list_sensors` |
+| **Device groups** | `list_devicegroups`, `get_devicegroup` |
+| **ARP** | `list_arp` |
+| **Services** | `list_services` |
+| **Inventory** | `get_inventory` |
+
+## Requirements
+
+- Python 3.9+
+- A LibreNMS instance with API access
+- An API token (LibreNMS web UI: **Settings > API > API Settings**)
+
+## Setup
+
+```bash
+# 1. Create and activate a virtual environment
+python -m venv .venv
+.venv\Scripts\activate        # Windows
+source .venv/bin/activate     # Linux/macOS
+
+# 2. Install the package (editable)
+pip install -e .
+
+# 3. Configure
+copy config.example.yaml config.yaml   # Windows
+# cp config.example.yaml config.yaml   # Linux/macOS
+# then edit config.yaml with your LibreNMS URL and API token
+```
+
+### Configuration
+
+`config.yaml` (gitignored — never commit it):
+
+```yaml
+librenms:
+  url: "http://your-librenms-host"   # base URL, no trailing slash
+  token: "your-api-token"            # LibreNMS web UI: Settings > API > API Settings
+```
+
+## Running
+
+The server speaks MCP over **streamable HTTP** by default, bound to `0.0.0.0:5757`:
+
+```bash
+# Console script (foreground)
+mcp-librenms --config config.yaml
+
+# Or as a module
+python -m mcp_librenms --config config.yaml
+```
+
+Endpoint: **http://\<IP\>:5757/mcp**
+
+### Options
+
+| Flag | Default | Description |
+|---|---|---|
+| `--config FILE` | `config.yaml` | Path to YAML config file (CWD, then project root) |
+| `--host IP` | `0.0.0.0` | Bind address |
+| `--port PORT` | `5757` | Bind port |
+| `--daemon` | off | Run in background (detached process) |
+| `--stdio` | off | Use stdio transport instead of HTTP |
+
+Examples:
+
+```bash
+# Background on a custom address/port
+mcp-librenms --config config.yaml --daemon --host 192.168.1.10 --port 8080
+# → http://192.168.1.10:8080/mcp
+
+# stdio transport (for MCP clients that spawn the server)
+mcp-librenms --config config.yaml --stdio
+```
+
+### MCP client configuration
+
+Example for any MCP client that supports streamable HTTP servers:
+
+```json
+{
+  "mcpServers": {
+    "librenms": {
+      "url": "http://your-librenms-host:5757/mcp"
+    }
+  }
+}
+```
+
+For stdio-based clients (Claude Desktop, etc.), spawn the server with `--stdio` and point `--config` at your config file:
+
+```json
+{
+  "mcpServers": {
+    "librenms": {
+      "command": "D:\\path\\to\\.venv\\Scripts\\mcp-librenms.exe",
+      "args": ["--config", "D:\\path\\to\\mcp-librenms\\config.yaml", "--stdio"]
+    }
+  }
+}
+```
+
+> **Note:** the client uses `verify=False` for TLS, so it works with LibreNMS instances behind self-signed certificates.
+
+## Project structure
+
+```
+mcp-librenms/
+├── config.example.yaml   # Template for local configuration
+├── config.yaml           # Your local configuration (gitignored)
+├── .gitignore
+├── README.md
+├── pyproject.toml        # Package metadata + console script
+├── requirements.txt      # Flat dependency list
+└── mcp_librenms/
+    ├── __init__.py
+    ├── __main__.py       # python -m mcp_librenms
+    ├── client.py         # LibreNMS REST API HTTP client
+    └── server.py         # MCP server + tool definitions
+```
+
+## License
+
+MIT

mcp_librenms-0.1.0/mcp_librenms.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+mcp_librenms/__init__.py
+mcp_librenms/__main__.py
+mcp_librenms/client.py
+mcp_librenms/server.py
+mcp_librenms.egg-info/PKG-INFO
+mcp_librenms.egg-info/SOURCES.txt
+mcp_librenms.egg-info/dependency_links.txt
+mcp_librenms.egg-info/entry_points.txt
+mcp_librenms.egg-info/requires.txt
+mcp_librenms.egg-info/top_level.txt

mcp_librenms-0.1.0/mcp_librenms.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mcp_librenms-0.1.0/mcp_librenms.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-librenms = mcp_librenms.server:run

mcp_librenms-0.1.0/mcp_librenms.egg-info/requires.txt

@@ -0,0 +1,3 @@
+fastmcp>=2.0.0
+httpx>=0.27.0
+pyyaml>=6.0

mcp_librenms-0.1.0/mcp_librenms.egg-info/top_level.txt

@@ -0,0 +1 @@
+mcp_librenms

mcp_librenms-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mcp-librenms"
+version = "0.1.0"
+description = "MCP server that exposes the LibreNMS REST API as MCP tools"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["mcp", "librenms", "monitoring", "snmp", "network"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Topic :: System :: Monitoring",
+]
+dependencies = [
+    "fastmcp>=2.0.0",
+    "httpx>=0.27.0",
+    "pyyaml>=6.0",
+]
+
+[project.scripts]
+mcp-librenms = "mcp_librenms.server:run"
+
+[tool.setuptools]
+packages = ["mcp_librenms"]

mcp_librenms-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+