grafana-log-mcp

grafana-log-mcp ist eine generische, wiederverwendbare Log-Abfrageschicht für Grafana/Loki, bereitgestellt als schreibgeschützter stdio-MCP-Server. Er kommuniziert mit der Grafana-API und liefert rohe Logs sowie aggregierte Ansichten – langsame Logs, Fehler-Fingerprints und Volumentrends – gefiltert nach Zeitfenster, Projekt, Schlüsselwort oder Dauerschwelle.

Er enthält bewusst keine geschäftsspezifische Logik oder Heuristiken. Sobald die Logs vorliegen, bleibt das Korrelieren mit dem Quellcode und das Erklären, warum etwas passiert ist, Ihrer KI-IDE und den Skills/Regeln des Geschäftsprojekts überlassen, das debuggt wird – der Server stellt die Daten lediglich bereit.

Positionierung (chinesisch): Dies ist eine generische Log-Abfrageschicht (nur Datenerfassung, Aggregation und Rückgabe von Logs, über Geschäftsprojekte hinweg wiederverwendbar), die keine Geschäftsanalyse oder Ursachenzuschreibung enthält; die konkrete Ursachenanalyse übernimmt die KI des Aufrufers in Verbindung mit dem Quellcode des Geschäftsprojekts und den projektbezogenen Skills/Erfahrungen.

Installation

# 方式一：npm 全局安装（推荐）
npm install -g grafana-log-mcp

Nach der globalen Installation stehen zwei Befehle zur Verfügung: grafana-log-mcp (startet den MCP-Server) und grafana-log-mcp-login (interaktive Anmeldung).

Alternativ kann es ohne Installation einmalig mit npx ausgeführt werden: npx -y grafana-log-mcp / npx -y grafana-log-mcp-login.

Related MCP server: grafana-mcp

Schnellstart

npm installiert (Konsument)

# 1. 登录（交互输入 Grafana 地址与用户名密码，写入 ~/.grafana-log-mcp/credentials.json，0600）
grafana-log-mcp-login

# 2. 校验凭证（排查"MCP 突然查不了"）
grafana-log-mcp-login --check

# 3. 启动 MCP Server（stdio）
grafana-log-mcp

Entwicklung aus dem Quellcode (nach dem Klonen des Repositorys)

# 1. 安装依赖（node >= 18）
npm install

# 2. 登录
node bin/login.js

# 3. 校验凭证
node bin/login.js --check

# 4. 启动 MCP Server（stdio）
npm start          # 即 node src/index.js

Anbindung an AI-IDEs (Trae/Claude usw.)

Fügen Sie Folgendes in der MCP-Konfiguration hinzu (gemäß dem Konfigurationsformat der jeweiligen IDE):

{
  "mcpServers": {
    "grafana-log": {
      "command": "npx",
      "args": ["-y", "grafana-log-mcp"],
      "env": { "GRAFANA_URL": "https://your-grafana.example.com" }
    }
  }
}

Empfohlen: global aktivieren: Beim Troubleshooting ist das Quellcode-Repository des Geschäftsprojekts geöffnet; mit globaler MCP-Konfiguration können Sie in jedem Repository direkt arbeiten: „fragen → Logs abrufen → Code lesen → Ursache benennen“.

Tools (15)

Drei harte Obergrenzen für die Datenmenge: limit ≤ 1000, 500 Zeichen pro Zeile, 25k Zeichen Antwort (bei Überschreitung werden Kopf und Ende beibehalten, die Mitte gekürzt und dies gekennzeichnet). Wenn eine Zeile abgeschnitten wird, kann mit get_full_line anhand der time dieser Zeile der vollständige Inhalt abgerufen werden.

Projektregistrierung (projects.json)

Die Projektregistrierungsdatei wird nach folgender Priorität lokalisiert (das von list_projects zurückgegebene summary.configFile zeigt den aktuell tatsächlich verwendeten Speicherort):

1. Die über die Umgebungsvariable GRAFANA_CONFIG_PATH angegebene Datei

2. config/projects.json innerhalb des Pakets (im Quellcode-Repository)

3. ~/.grafana-log-mcp/projects.json (im selben Verzeichnis wie die Anmeldedaten; Standardort nach npm-Installation)

Ein Referenzformat finden Sie in config/projects.example.json; jeder Eintrag enthält key / datasourceUid / labels{app,group} / aliases(中文别名) / repoPath. repoPath dient nur der KI-IDE zum Auffinden des Codes; der MCP selbst liest keinen Quellcode. Die Fehler-Wissensdatenbank befindet sich in config/failure-patterns.json; bei neuen Fehlertypen kann einfach ein Eintrag hinzugefügt werden.

Umgebungsvariablen (optional)

GRAFANA_URL=                  # Grafana 地址：作为 grafana-log-mcp-login 的默认地址，并覆盖凭证文件中的地址
GRAFANA_ORG_ID=1              # 可选：仅影响 build_explore_url 生成的 Explore 深链的 orgId 参数（默认 1）；不参与实际日志查询
GRAFANA_CREDENTIALS_PATH=     # 自定义凭证文件位置
GRAFANA_CONFIG_PATH=          # 自定义项目登记文件（projects.json）位置
GRAFANA_MOCK=1                # 本地 mock 模式：不连真实 Grafana、无需登录（2500 条合成日志，验证翻页/截断/慢日志）

Hinweis: Der MCP enthält keine eingebauten Standard-Grafana-Adressen oder Projektkonfigurationen (er ist generisch gehalten). Die Adresse stammt aus der Eingabe bei der Anmeldung (Anmeldedatei) oder aus der Umgebungsvariable GRAFANA_URL; instanzbezogene Konfigurationen (Projektregistrierung, Datenquellen-UIDs) werden in projects.json gepflegt (siehe Lokalisierungsregeln im vorherigen Abschnitt).

Tests

node test/unit.mjs         # 纯逻辑单测（合成日志，无网络依赖）：59 通过
node test/integration.mjs  # 编排器端到端（mock client + 独立 fixture 配置）：20 通过