grafana-mcp

Предоставляет часть API Grafana в качестве MCP-сервера (Model Context Protocol), ориентированного на запросы к логам на естественном языке. Основная цель: сказать «покажи мне логи ошибок от сервиса api за последние 30 минут» и получить реальные строки логов — без необходимости вручную работать с LogQL, метками или UID источников данных.

Источники данных логов, метки Loki и сопоставление имени сервиса с его хостинговым источником данных/меткой кэшируются на диске, поэтому повторные вызовы пропускают избыточное сканирование меток.

한국어 문서 / Korean README

Установка и настройка

npx (установка не требуется)

Добавьте следующее в ~/.mcp.json.

{
  "mcpServers": {
    "grafana": {
      "command": "npx",
      "args": ["@seungje.jun/grafana-mcp"],
      "env": {
        "GRAFANA_URL": "https://grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxx"
      }
    }
  }
}

Сборка из исходного кода

git clone https://github.com/ninanung/grafana-mcp.git
cd grafana-mcp
npm install
npm run build

{
  "mcpServers": {
    "grafana": {
      "command": "node",
      "args": ["/path/to/grafana-mcp/dist/cli.js"],
      "env": {
        "GRAFANA_URL": "https://grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxx"
      }
    }
  }
}

Перезапустите Claude Code, чтобы активировать инструменты MCP.

Аутентификация

Требуется один из следующих вариантов. Они проверяются в указанном ниже порядке — побеждает первый найденный.

Все токены типа bearer отправляются как Authorization: Bearer <token>. Серверу не важно, какой это тип токена — он просто выбирает тот, который установлен.

Переменные окружения

Related MCP server: Log Analyzer MCP Server

Инструменты

Пример использования

Типичный сценарий на естественном языке, управляемый клиентом MCP:

1. Пользователь: «Покажи мне логи ошибок от сервиса api за последние 30 минут.»

2. query_logs с service: "api", level: "error", time_from: "now-30m" → сервер автоматически определяет, какой источник данных Loki владеет меткой service="api", и выполняет LogQL.

3. (Первый вызов) сопоставление сервис → источник данных/метка сохраняется в кэш; последующие вызовы пропускают этап обнаружения.

4. Пользователь: «Обобщи эти ошибки по шаблону.» → тот же вызов с output: "summarize" возвращает количество, сгруппированное по шаблонам.

5. Пользователь: «Какие еще сервисы у нас есть?» → list_services возвращает полный список сервисов.

Если в имени сервиса есть опечатка, query_logs предложит похожие варианты (например, Did you mean: checkout, checkout-api?).

Как работает автообнаружение

query_logs самостоятельно выбирает целевой источник данных и метку:

1. Фильтрует все источники данных, оставляя только типы логов (Loki/ES/CloudWatch/OpenSearch/Splunk).

2. Для каждого источника данных Loki получает /loki/api/v1/labels и сначала проходит по общим кандидатам на метку сервиса (service, service_name, app, app_name, application, container, job), а затем по всем остальным меткам.

3. Для каждой метки-кандидата получает ее значения и проверяет, есть ли запрошенное имя service в этом списке.

4. Если совпадает ровно одна пара (datasource, label), использует ее. Если совпадает несколько, требует datasource_uid для уточнения. Если совпадений нет, возвращает предложения с похожими именами.

5. Разрешенная пара (service → ds_uid, label) кэшируется; refresh: true или refresh_log_cache принудительно запускают повторное обнаружение.

Автообнаружение в настоящее время поддерживает только Loki. Для источников данных Elasticsearch / CloudWatch / Splunk передавайте datasource_uid и service_label явно (и не ожидайте применения специфичных для LogQL фильтров).

Режимы вывода

query_logs принимает параметр output:

• raw (по умолчанию): <ISO timestamp> <log line> — удобно для прямого чтения в терминале.

• summarize: группирует строки по нормализованному шаблону (числа → N, UUID → UUID) с количеством и примером для каждого шаблона. Используйте, когда строки зашумлены или их слишком много.

• json: структурированные объекты { ts, line, labels } — для последующей обработки инструментами.

Кэш

• Кэш логов: сохраняется в ~/.grafana-mcp/log-cache.json. Ключом является базовый URL Grafana, чтобы экземпляры не конфликтовали.

• Каждая категория имеет свой TTL (источники данных / метки / значения меток / разрешение сервисов) — см. таблицу переменных окружения выше.

• Разрешение сервиса, которое позже перестало работать (например, метка была переименована), автоматически аннулируется, чтобы следующий вызов выполнил повторное обнаружение.

• Используйте get_log_cache для просмотра, refresh_log_cache для очистки, и export_log_cache / import_log_cache для обмена с коллегами.

Расположение и сброс кэша

Файл кэша — это обычный JSON-документ, его безопасно просматривать, редактировать или создавать резервные копии вручную.

Безопасность и ограничения

• Только чтение: сервер не предоставляет никаких эндпоинтов, изменяющих состояние Grafana. Никакого CRUD дашбордов/источников данных, никаких изменений алертов.

• Логи Stdio: все логи направляются в stderr, сохраняя канал stdio MCP чистым.

• Пропуск TLS: GRAFANA_TLS_SKIP_VERIFY=true устанавливает NODE_TLS_REJECT_UNAUTHORIZED=0 для всего процесса. Используйте только для самоподписанной Grafana в доверенных сетях.

• Никакого логирования секретов: токены аутентификации никогда не записываются в логи аудита.

Лицензия

MIT