grafana-log-mcp

grafana-log-mcp — это универсальный, переиспользуемый слой запросов к логам для Grafana/Loki, предоставляемый как MCP-сервер с доступом только на чтение через stdio. Он взаимодействует с API Grafana и возвращает необработанные логи, а также агрегированные представления — медленные запросы, сигнатуры ошибок и тренды объёмов — с фильтрацией по временному окну, проекту, ключевому слову или порогу длительности.

Он намеренно не содержит бизнес-специфичной логики или эвристик. Когда логи получены, сопоставление их с исходным кодом и объяснение почему что-то произошло остаётся на усмотрение вашей AI IDE и навыков/правил отлаживаемого бизнес-проекта — сервер просто делает данные доступными.

Позиционирование: это универсальный слой запросов к логам (только извлечение, агрегация и возврат логов, переиспользуемый между проектами), без встроенного бизнес-анализа и определения первопричин; конкретный анализ причин выполняется AI вызывающей стороны совместно с исходным кодом бизнес-проекта и собственными навыками/опытом проекта.

Установка

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

После глобальной установки доступны две команды: grafana-log-mcp (запуск MCP-сервера) и grafana-log-mcp-login (интерактивный вход).

Можно также не устанавливать, а запустить однократно через npx: npx -y grafana-log-mcp / npx -y grafana-log-mcp-login.

Related MCP server: grafana-mcp

Быстрый старт

npm установлен (потребитель)

# 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

Разработка из исходников (после клонирования репозитория)

# 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

Подключение к AI IDE (Trae/Claude и др.)

Добавьте в конфигурацию MCP (в соответствии с форматом конфигурации вашей IDE):

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

Рекомендуется глобальное включение: при устранении неполадок открыт репозиторий с исходным кодом бизнес-проекта; добавьте конфигурацию MCP глобально, и в любом репозитории можно будет напрямую «задать вопрос → посмотреть логи → прочитать код → дать причину».

Инструменты (15)

Три жёстких ограничения объёма данных: limit ≤ 1000, 500 символов на строку, 25k символов в ответе (при превышении сохраняются начало и конец, середина сокращается с пометкой). Если строка обрезана, можно использовать get_full_line для получения полного содержимого по time этой строки.

Регистрация проектов (projects.json)

Файл регистрации определяется по следующему приоритету (summary.configFile, возвращаемый list_projects, показывает фактически используемое расположение):

1. Файл, указанный переменной окружения GRAFANA_CONFIG_PATH

2. config/projects.json внутри пакета (в репозитории исходного кода)

3. ~/.grafana-log-mcp/projects.json (в той же директории, что и учётные данные; расположение по умолчанию после установки через npm)

Пример формата см. в config/projects.example.json; каждая запись содержит key / datasourceUid / labels{app,group} / aliases(中文别名) / repoPath. repoPath используется только AI IDE для поиска кода; сам MCP не читает исходный код. База знаний о сбоях находится в config/failure-patterns.json — при обнаружении нового типа сбоя просто добавьте запись.

Переменные окружения (необязательно)

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 条合成日志，验证翻页/截断/慢日志）

Примечание: MCP не содержит встроенных адресов Grafana по умолчанию и конфигурации проектов (универсальность); адрес берётся из введённого при входе (файл учётных данных) или из переменной окружения GRAFANA_URL; конфигурация, связанная с экземпляром (регистрация проектов, uid источника данных), поддерживается в projects.json (см. правила определения расположения в предыдущем разделе).

Тестирование

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