Grafana

официальный

Поиск дашбордов, расследование инцидентов и выполнение запросов к источникам данных в вашем экземпляре Grafana

GitHub
3.4k

Что можно делать с Grafana MCP?

  • Поиск и просмотр дашбордов — Используйте search_dashboards и get_dashboard_summary для поиска дашбордов и получения компактных обзоров без полного JSON.
  • Запросы к Prometheus и Loki — Выполняйте запросы PromQL и LogQL к вашим источникам данных, включая метаданные и процентили гистограмм.
  • Управление оповещениями — Список, создание, обновление и удаление правил оповещений, а также просмотр политик уведомлений и контактных точек.
  • Создание глубоких ссылок — Создавайте точные URL-адреса для дашбордов, панелей и Explore с временными диапазонами с помощью инструментов навигации.
  • Выполнение запросов панелей — Выполняйте запрос панели дашборда с пользовательскими временными диапазонами и переменными с помощью run_panel_query.

Документация

MCP-сервер Grafana

Unit Tests Integration Tests E2E Tests Go Reference MCP Catalog

MCP-сервер для Grafana, реализующий Model Context Protocol.

Он предоставляет доступ к вашему экземпляру Grafana и окружающей экосистеме.

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

Требуется uv. Добавьте следующее в конфигурацию вашего MCP-клиента (например, Claude Desktop, Cursor):

{
  "mcpServers": {
    "grafana": {
      "command": "uvx",
      "args": ["mcp-grafana"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Для Grafana Cloud замените GRAFANA_URL на URL вашего экземпляра (например, https://myinstance.grafana.net). Дополнительные варианты установки, включая Docker, бинарный файл и Helm, см. в разделе Использование.

Требования

  • Требуется Grafana версии 9.0 или новее для полной функциональности. Некоторые функции, особенно операции, связанные с источниками данных, могут некорректно работать с более ранними версиями из-за отсутствующих конечных точек API.

Возможности

Следующие возможности в настоящее время доступны в MCP-сервере. Этот список приведён только в информационных целях и не является дорожной картой или обязательством по реализации будущих функций.

Панели (Dashboards)

  • Поиск панелей: поиск панелей по названию или другим метаданным
  • Получить панель по UID: получение полных сведений о панели по её уникальному идентификатору. Предупреждение: большие панели могут занимать значительный объём контекстного окна.
  • Получить сводку по панели: получение компактного обзора панели, включая название, количество панелей, типы панелей, переменные и метаданные, без полного JSON, чтобы минимизировать использование контекстного окна
  • Получить свойство панели: извлечение отдельных частей панели с помощью выражений JSONPath (например, $.title, $.panels[*].title), чтобы получать только нужные данные и снижать потребление контекстного окна
  • Обновить или создать панель: изменение существующих панелей или создание новых. Предупреждение: требуется полный JSON панели, который может занимать большой объём контекстного окна.
  • Частичное обновление панели: внесение точечных изменений в панель без необходимости полного JSON, что значительно снижает использование контекстного окна при целевых правках
  • Получить запросы панелей и информацию об источниках данных: получение названия, строки запроса и информации об источнике данных (включая UID и тип, если доступны) для каждой панели в дашборде

Выполнение запроса панели

Примечание: инструменты выполнения запросов панелей отключены по умолчанию. Чтобы включить их, добавьте runpanelquery в ваш флаг --enabled-tools.

  • Выполнить запрос панели: выполнение запроса панели дашборда с пользовательскими временными диапазонами и переопределениями переменных.

Управление контекстным окном

Инструменты для работы с панелями теперь включают несколько стратегий для эффективного управления использованием контекстного окна (issue #101):

  • Используйте get_dashboard_summary для обзора панели и планирования изменений
  • Используйте get_dashboard_property с JSONPath, когда нужны только отдельные части панели
  • Избегайте get_dashboard_by_uid, если вам не нужен полный JSON панели

Источники данных

  • Перечислить и получить информацию об источниках данных: просмотр всех настроенных источников данных и получение подробной информации о каждом из них.
    • Поддерживаемые типы источников данных: Prometheus, Loki, ClickHouse, CloudWatch, Elasticsearch, OpenSearch, Snowflake, Athena.

Примеры запросов

Примечание: инструменты примеров запросов отключены по умолчанию. Чтобы включить их, добавьте examples в ваш флаг --enabled-tools.

  • Получить примеры запросов: получение примеров запросов для различных типов источников данных, чтобы изучить синтаксис запросов.

Запросы к Prometheus

  • Запрос к Prometheus: выполнение запросов PromQL (поддерживаются как мгновенные, так и диапазонные запросы метрик) к источникам данных Prometheus.
  • Запрос метаданных Prometheus: получение метаданных метрик, имён метрик, имён меток и значений меток из источников данных Prometheus.
  • Запрос процентилей гистограммы: вычисление значений процентилей гистограммы (p50, p90, p95, p99) с помощью histogram_quantile.

Запросы к Loki

  • Запрос логов и метрик Loki: выполнение как запросов логов, так и запросов метрик с использованием LogQL к источникам данных Loki.
  • Запрос метаданных Loki: получение имён меток, значений меток и статистики потоков из источников данных Loki.
  • Запрос паттернов Loki: получение паттернов логов, обнаруженных Loki, для выявления типовых структур логов и аномалий.

Запросы к InfluxDB

Примечание: инструменты InfluxDB отключены по умолчанию. Чтобы включить их, добавьте influxdb в ваш флаг --enabled-tools.

  • Запрос к InfluxDB: выполнение запросов к источникам данных InfluxDB с использованием InfluxQL (v1.x) или Flux (v2.x). Диалект определяется автоматически из конфигурации источника данных или может быть задан явно через параметр dialect.

Запросы к ClickHouse

Примечание: инструменты ClickHouse отключены по умолчанию. Чтобы включить их, добавьте clickhouse в ваш флаг --enabled-tools.

  • Перечислить таблицы ClickHouse: список всех таблиц в базе данных ClickHouse с количеством строк и размерами.
  • Описать схему таблицы: получение имён столбцов, типов и метаданных для таблицы ClickHouse.
  • Запрос к ClickHouse: выполнение SQL-запросов с поддержкой макросов Grafana и подстановки переменных.

Запросы к CloudWatch

Примечание: инструменты CloudWatch отключены по умолчанию. Чтобы включить их, добавьте cloudwatch в ваш флаг --enabled-tools.

  • Перечислить пространства имён CloudWatch: обнаружение доступных пространств имён AWS CloudWatch.
  • Перечислить метрики CloudWatch: список метрик, доступных в конкретном пространстве имён.
  • Перечислить измерения CloudWatch: получение измерений для фильтрации запросов метрик.
  • Запрос к CloudWatch: выполнение запросов метрик CloudWatch с поддержкой временных диапазонов.

Запросы к Graphite

Примечание: инструменты Graphite отключены по умолчанию. Чтобы включить их, добавьте graphite в ваш флаг --enabled-tools.

  • Запрос к Graphite: выполнение запросов к Graphite render API для источника данных Graphite.
  • Перечислить метрики Graphite: просмотр и обнаружение путей метрик Graphite.
  • Перечислить теги Graphite: список доступных тегов Graphite и значений тегов.
  • Запрос плотности Graphite: запрос плотности метрик Graphite для заданного шаблона.

Запросы к Athena

Примечание: инструменты Athena отключены по умолчанию. Чтобы включить их, добавьте athena в ваш флаг --enabled-tools.

  • Перечислить каталоги Athena: обнаружение доступных каталогов данных (например, AwsDataCatalog, коннекторы Iceberg).
  • Перечислить базы данных Athena: список баз данных в каталоге Athena.
  • Перечислить таблицы Athena: список таблиц в базе данных Athena.
  • Описать таблицу Athena: получение имён столбцов для таблицы Athena.
  • Запрос к Athena: выполнение SQL-запросов к Amazon Athena через Grafana с подстановкой макросов, ограничением количества результатов и поддержкой переменных шаблонов.

Запросы к Snowflake

Примечание: инструменты Snowflake отключены по умолчанию. Чтобы включить их, добавьте snowflake в ваш флаг --enabled-tools.

Запросы выполняются через источник данных Snowflake в Grafana (плагин Grafana Enterprise grafana-snowflake-datasource), поэтому аутентификация обрабатывается конфигурацией источника данных в Grafana — учётные данные никогда не видны MCP-серверу. Это та же модель, что используется для инструментов ClickHouse.

  • Перечислить таблицы Snowflake: обнаружение таблиц (с базой данных, схемой, типом, количеством строк и размером) через INFORMATION_SCHEMA.TABLES. Доступны необязательные фильтры по базе данных/схеме.
  • Описать схему таблицы: получение имён столбцов, типов данных, допустимости NULL, значений по умолчанию и комментариев для таблицы Snowflake.
  • Запрос к Snowflake: выполнение SQL-запросов с поддержкой макросов и подстановки переменных. Полезно для запросов к таблицам событий Snowflake (например, SNOWFLAKE.TELEMETRY.EVENTS) для логов и трейсов, а также к любым пользовательским таблицам.
    • Поддерживаемые макросы: $__timeFilter(column), $__timeFrom, $__timeTo, $__from, $__to (мс Unix), $__interval (секунды), $__interval_ms и ${varname} для подстановки переменных шаблонов.

Запросы к Elasticsearch/OpenSearch

Примечание: инструменты Elasticsearch/OpenSearch отключены по умолчанию. Чтобы включить их, добавьте elasticsearch в ваш флаг --enabled-tools.

  • Запрос к Elasticsearch/OpenSearch: выполнение поисковых запросов к источникам данных Elasticsearch или OpenSearch с использованием синтаксиса запросов Lucene или Elasticsearch Query DSL. Поддерживается фильтрация по временному диапазону и получение логов, метрик или любых индексированных данных. Возвращает документы с их индексом, ID, полями источника и необязательной оценкой релевантности.

Запросы к Quickwit

Примечание: инструменты Quickwit отключены по умолчанию. Чтобы включить их, добавьте quickwit в ваш флаг --enabled-tools.

  • Запрос к Quickwit: выполнение поисковых запросов к источникам данных Quickwit с использованием синтаксиса запросов Lucene или частично совместимого с Elasticsearch Query DSL. Поддерживается фильтрация по временному диапазону и получение логов или других индексированных документов. Возвращает документы с их индексом, ID, полями источника и необязательной оценкой релевантности.

Наблюдаемость агентов

Примечание: инструменты наблюдаемости агентов отключены по умолчанию и работают только в Grafana Cloud. Чтобы включить их, добавьте agento11y в ваш флаг --enabled-tools.

  • Список и поиск диалогов: список недавних LLM-диалогов или их поиск с помощью выражения фильтра (модель, провайдер, агент, статус, тип ошибки, результаты оценки и другое) за временной диапазон. Результаты поиска включают количество ошибок, сводки оценок, сводки результатов оценки и ID трейсов.
  • Получить сведения о диалоге: получение одного диалога со всеми его генерациями, включая промпты и выходные данные.
  • Получить сведения о генерации и оценки: получение одной генерации по ID и её оценок (оценщик, ключ оценки, значение, пройдено, пояснение).
  • Чтение каталога агентов: список агентов, отправляющих телеметрию, получение полной версии одного агента (полный системный промпт, каждый инструмент с его JSON-схемой и модели, на которых он работал), просмотр истории версий агента и сравнение агрегированных оценок по версиям. Эффективные версии — это хэши sha256:, на которые никогда не влияет изменение инструмента; для агента, не сообщающего собственную версию, хэшируется системный промпт, поэтому правка промпта создаёт новую версию. Строки каталога и версий содержат token_estimate, который стоит проверить перед получением полного промпта.
  • Просмотр оценщиков и шаблонов: чтение оценщиков, от которых получена оценка, шаблонов, на основе которых они созданы, а также провайдеров и моделей-судей, доступных оценщикам на основе LLM. При включённых инструментах записи также можно создавать, клонировать, тестировать и удалять оценщиков.
  • Просмотр правил оценки и защитных правил: чтение асинхронных правил оценки, связывающих оценщиков с производственным трафиком, и защитных правил (hook rules), которые выполняются встроенно и могут предупреждать или запрещать. При включённых инструментах записи также можно создавать, обновлять, просматривать и удалять их. Записи и непостоянные операции preview_rule и test_evaluator требуют разрешения grafana-agento11y-app.eval:write, предоставляемого ролью Agento11y Admin.
  • Управление сохранёнными диалогами и коллекциями: чтение сохранённых диалогов (закладок, которые дают диалогу стабильный ID, имя и теги) и коллекций, которые их группируют, включая количество участников каждой коллекции и коллекции, встроенные в каждую строку сохранённого диалога. При включённых инструментах записи также можно добавлять диалог в закладки, создавать и редактировать коллекции, добавлять и удалять участников. Эти записи требуют того же разрешения grafana-agento11y-app.eval:write.
  • Чтение и редактирование тестовых наборов: список версионированных тестовых наборов, на которых выполняются офлайн-эксперименты, чтение одного набора с полной историей версий и постраничный просмотр тестовых случаев версии. При включённых инструментах записи также можно создать набор, переименовать или изменить его теги, открыть черновую версию, опубликовать её, а также записать или удалить её тестовые случаи. Опубликованная версия заморожена, поэтому правка означает открытие нового черновика. Эти записи требуют grafana-agento11y-app.eval:write.
  • Чтение офлайн-экспериментов: список прогонов оценки по тестовому набору и чтение одного из них с основным показателем прохождения, стоимостью и общим количеством токенов. Детализация через отчёт по каждому тестовому случаю до испытаний, их оценок с пояснением каждого судьи и метаданных артефактов. При включённых инструментах записи также можно переименовать или изменить теги эксперимента и отменить выполняющийся, для чего требуется grafana-agento11y-app.eval:write. Эксперименты создаются SDK-раннерами, а не этим инструментом.

Grafana Assistant

Примечание: Инструменты ассистента по умолчанию отключены и требуют установки плагина Grafana Assistant (grafana-assistant-app) на целевой экземпляр Grafana. Они также являются инструментами записи (ассистент может изменять состояние стека), поэтому они пропускаются, когда установлен --disable-write. Чтобы включить их, добавьте assistant к вашему флагу --enabled-tools.

  • Запрос к ассистенту: Отправьте запрос на естественном языке в Grafana Assistant и дождитесь полного текстового ответа. Ассистент может использовать инструменты, метрики, логи и другой контекст стека — шире, чем выполнение одного изолированного запроса к источнику данных. Передайте возвращённый contextId обратно в последующем вызове, чтобы продолжить тот же разговор. Сложные задачи могут занять несколько минут; вызов блокируется до завершения ответа или истечения времени ожидания запроса (5 минут).

Инциденты

  • Поиск, создание и обновление инцидентов: Управление инцидентами в Grafana Incident, включая поиск, создание и добавление действий к инцидентам.

Расследования Sift

  • Список расследований Sift: Получение списка расследований Sift с поддержкой параметра ограничения количества.
  • Получение расследования Sift: Получение деталей конкретного расследования Sift по его UUID.
  • Получение анализов Sift: Получение конкретного анализа из расследования Sift.
  • Поиск шаблонов ошибок в журналах: Обнаружение повышенных шаблонов ошибок в журналах Loki с помощью Sift.
  • Поиск медленных запросов: Обнаружение медленных запросов с помощью Sift (Tempo).

Оповещения

  • Список и получение информации о правилах оповещения: Просмотр правил оповещения и их статусов (срабатывание/норма/ошибка и т. д.) в Grafana. Поддерживает правила, управляемые Grafana, и правила, управляемые источниками данных Prometheus или Loki.
  • Создание и обновление правил оповещения: Создание новых правил оповещения или изменение существующих.
  • Удаление правил оповещения: Удаление правил оповещения по UID.
  • Управление маршрутизацией оповещений: Просмотр политик уведомлений, контактных точек и временных интервалов. Поддерживает контактные точки, управляемые Grafana, и получателей из внешних источников данных Alertmanager (Prometheus Alertmanager, Mimir, Cortex).

Grafana OnCall

  • Список и управление расписаниями: Просмотр и управление расписаниями дежурств в Grafana OnCall.
  • Получение деталей смены: Получение подробной информации о конкретных дежурных сменах.
  • Получение текущих дежурных: Просмотр пользователей, которые в данный момент дежурят по расписанию.
  • Список команд и пользователей: Просмотр всех команд и пользователей OnCall.
  • Список групп оповещений: Просмотр и фильтрация групп оповещений из Grafana OnCall по различным критериям, включая состояние, интеграцию, метки и временной диапазон.
  • Получение деталей группы оповещений: Получение подробной информации о конкретной группе оповещений по её ID.

Администрирование

Примечание: Инструменты администрирования по умолчанию отключены. Чтобы включить их, добавьте admin в ваш флаг --enabled-tools.

  • Список команд: Просмотр всех настроенных команд в Grafana.
  • Список пользователей: Просмотр всех пользователей в организации в Grafana.
  • Список всех ролей: Перечисление всех ролей Grafana с необязательным фильтром для делегируемых ролей.
  • Получение деталей роли: Получение деталей конкретной роли Grafana по UID.
  • Список назначений для роли: Перечисление всех пользователей, команд и сервисных аккаунтов, назначенных на роль.
  • Список ролей для пользователей: Перечисление всех ролей, назначенных одному или нескольким пользователям.
  • Список ролей для команд: Перечисление всех ролей, назначенных одной или нескольким командам.
  • Список разрешений для ресурса: Перечисление всех разрешений, определённых для конкретного ресурса (панель мониторинга, источник данных, папка и т. д.).
  • Описание ресурса Grafana: Перечисление доступных разрешений и возможностей назначения для типа ресурса.

Навигация

  • Генерация глубоких ссылок: Создание точных URL-адресов глубоких ссылок для ресурсов Grafana вместо использования предположений LLM по URL-адресам.
    • Ссылки на панели мониторинга: Генерация прямых ссылок на панели мониторинга по их UID (например, http://localhost:3000/d/dashboard-uid)
    • Ссылки на панели: Создание ссылок на конкретные панели внутри панелей мониторинга с параметром viewPanel (например, http://localhost:3000/d/dashboard-uid?viewPanel=5)
    • Ссылки для Explore: Генерация ссылок на Grafana Explore с предварительно настроенными источниками данных (например, http://localhost:3000/explore?left={"datasource":"prometheus-uid"})
    • Поддержка временного диапазона: Добавление параметров временного диапазона к ссылкам (from=now-1h&to=now)
    • Пользовательские параметры: Включение дополнительных параметров запроса, таких как переменные панели мониторинга или интервалы обновления

Аннотации

  • Получение аннотаций: Запрос аннотаций с фильтрами. Поддерживает временной диапазон, UID панели мониторинга, теги и режим соответствия.
  • Создание аннотации: Создание новой аннотации на панели мониторинга или панели.
  • Создание аннотации Graphite: Создание аннотаций в формате Graphite (what, when, tags, data).
  • Обновление аннотации: Замена всех полей существующей аннотации (полное обновление).
  • Частичное обновление аннотации: Обновление только определённых полей аннотации (частичное обновление).
  • Получение тегов аннотаций: Перечисление доступных тегов аннотаций с необязательной фильтрацией.

Снимки

  • Список снимков: Перечисление снимков панелей мониторинга с необязательными фильтрами запроса и ограничения.
  • Получение снимка: Получение метаданных снимка и полезной нагрузки панели мониторинга по ключу снимка.
  • Создание снимка: Создание снимка панели мониторинга из полной полезной нагрузки панели мониторинга с необязательными параметрами срока действия и внешнего снимка.
  • Удаление снимка: Удаление снимка по ключу снимка.

Рендеринг

  • Получение изображения панели или панели мониторинга: Рендеринг панели панели мониторинга Grafana или всей панели мониторинга в виде изображения PNG. Возвращает изображение в виде данных в кодировке base64 для использования в отчётах, оповещениях или презентациях. Поддерживает настройку размеров, временного диапазона, темы, масштаба и переменных панели мониторинга. Также поддерживает рендеринг ещё не применённых панелей мониторинга из ветки репозитория подготовки (например, предварительный просмотр PR в git-sync) через необязательный параметр provisioningPreview.
    • Примечание: Требуется установка и настройка сервиса Grafana Image Renderer.

Провижининг

  • Список репозиториев подготовки: Перечисление репозиториев подготовки, настроенных для этого экземпляра Grafana (например, источников git-sync), с возвратом слага каждого репозитория вместе с его исходным URL, веткой, путём, состоянием синхронизации и статусом здоровья.
  • Проверка файла подготовки: Сухой запуск применения файла из репозитория подготовки в указанной ветке или коммите. Возвращает, будет ли он принят, действие ресурса (создание/обновление), целевой тип ресурса и любые структурированные ошибки проверки — та же поверхность допуска, которую использует комментатор PR в Grafana.

Список инструментов настраивается, поэтому вы можете выбрать, какие инструменты вы хотите сделать доступными для MCP-клиента. Это полезно, если вы не используете определённые функции или не хотите занимать слишком много контекстного окна. Чтобы отключить категорию инструментов, используйте флаг --disable-<category> при запуске сервера. Например, чтобы отключить инструменты OnCall, используйте --disable-oncall, или чтобы отключить генерацию глубоких ссылок навигации, используйте --disable-navigation.

Разрешения RBAC

Каждый инструмент требует определённых разрешений RBAC для правильной работы. При создании сервисного аккаунта для MCP-сервера убедитесь, что у него есть необходимые разрешения в зависимости от того, какие инструменты вы планируете использовать. Перечисленные разрешения — это минимально необходимые действия; вам также могут понадобиться соответствующие области действия (например, datasources:*, dashboards:*, folders:*) в зависимости от вашего сценария использования.

Совет: Если вы не знакомы с RBAC в Grafana или хотите более быструю и простую настройку вместо настройки множества детальных областей действия, вы можете назначить встроенную роль, такую как Editor, сервисному аккаунту. Роль Editor предоставляет широкий доступ на чтение/запись, который позволит выполнять большинство операций MCP-сервера; она менее детализирована (и, следовательно, менее ограничивающая), чем области действия, применяемые вручную, поэтому используйте её только тогда, когда удобство важнее строгого принципа минимальных привилегий.

Примечание: Инструменты Grafana Incident и Sift используют базовые роли Grafana вместо детализированных разрешений RBAC:

  • Роль Viewer: Требуется для операций только для чтения (список инцидентов, получение расследований)
  • Роль Editor: Требуется для операций записи (создание инцидентов, изменение расследований)

Для получения дополнительной информации о RBAC в Grafana см. официальную документацию.

Области действия RBAC

Области действия определяют конкретные ресурсы, к которым применяются разрешения. Каждое действие требует комбинации соответствующего разрешения и области действия.

Распространённые шаблоны областей действия:

  • Широкий доступ: Используйте подстановочные знаки * для доступа на уровне организации

    • datasources:* — доступ ко всем источникам данных
    • dashboards:* — доступ ко всем панелям мониторинга
    • folders:* — доступ ко всем папкам
    • teams:* — доступ ко всем командам

  • Ограниченный доступ: Используйте конкретные UID или ID для ограничения доступа к отдельным ресурсам

    • datasources:uid:prometheus-uid — доступ только к конкретному источнику данных Prometheus
    • dashboards:uid:abc123 — доступ только к панели мониторинга с UID abc123
    • folders:uid:xyz789 — доступ только к папке с UID xyz789
    • teams:id:5 — доступ только к команде с ID 5
    • global.users:id:123 — доступ только к пользователю с ID 123

Примеры:

  • Полный доступ к MCP-серверу: Предоставление широких разрешений для всех инструментов

    datasources:* (datasources:read, datasources:query)
dashboards:* (dashboards:read, dashboards:create, dashboards:write)
folders:* (for dashboard creation and alert rules)
teams:* (teams:read)
global.users:* (users:read)

  • Ограниченный доступ к источникам данных: Только запросы к конкретным экземплярам Prometheus и Loki

    datasources:uid:prometheus-prod (datasources:query)
datasources:uid:loki-prod (datasources:query)

  • Доступ к конкретной панели мониторинга: Чтение только определённых панелей мониторинга

    dashboards:uid:monitoring-dashboard (dashboards:read)
dashboards:uid:alerts-dashboard (dashboards:read)

Инструменты

ИнструментКатегорияОписаниеТребуемые разрешения RBACТребуемые области
list_teamsАдминистрированиеПеречислить все командыteams:readteams:* или teams:id:1
list_users_by_orgАдминистрированиеПеречислить всех пользователей организацииusers:readglobal.users:* или global.users:id:123
list_all_rolesАдминистрированиеПеречислить все роли Grafanaroles:readroles:*
get_role_detailsАдминистрированиеПолучить сведения о роли Grafanaroles:readroles:uid:editor
get_role_assignmentsАдминистрированиеПеречислить назначения для ролиroles:readroles:uid:editor
list_user_rolesАдминистрированиеПеречислить роли для пользователейroles:readglobal.users:id:123
list_team_rolesАдминистрированиеПеречислить роли для командroles:readteams:id:7
get_resource_permissionsАдминистрированиеПеречислить разрешения для ресурсаpermissions:readdashboards:uid:abcd1234
get_resource_descriptionАдминистрированиеОписать тип ресурса Grafanapermissions:readdashboards:*
search_dashboardsПоискИскать дашбордыdashboards:readdashboards:* или dashboards:uid:abc123
get_dashboard_by_uidДашбордыПолучить дашборд по uiddashboards:readdashboards:uid:abc123
update_dashboardДашбордыОбновить или создать новый дашбордdashboards:create, dashboards:writedashboards:*, folders:* или folders:uid:xyz789
get_dashboard_panel_queriesДашбордыПолучить заголовок панели, запросы, UID источника данных и тип из дашбордаdashboards:readdashboards:uid:abc123
run_panel_queryRunPanelQuery*Выполнить один или несколько запросов панелей дашбордаdashboards:read, datasources:querydashboards:uid:*, datasources:uid:*
get_dashboard_propertyДашбордыИзвлечь отдельные части дашборда с помощью выражений JSONPathdashboards:readdashboards:uid:abc123
get_dashboard_summaryДашбордыПолучить компактную сводку дашборда без полного JSONdashboards:readdashboards:uid:abc123
list_datasourcesИсточники данныхПеречислить источники данныхdatasources:readdatasources:*
get_datasourceИсточники данныхПолучить источник данных по UID или имениdatasources:readdatasources:uid:prometheus-uid
get_query_examplesПримеры*Получить примеры запросов для типа источника данныхdatasources:readdatasources:*
query_prometheusPrometheusВыполнить запрос к источнику данных Prometheusdatasources:querydatasources:uid:prometheus-uid
list_prometheus_metric_metadataPrometheusПеречислить метаданные метрикdatasources:querydatasources:uid:prometheus-uid
list_prometheus_metric_namesPrometheusПеречислить доступные имена метрикdatasources:querydatasources:uid:prometheus-uid
list_prometheus_label_namesPrometheusПеречислить имена меток, соответствующих селекторуdatasources:querydatasources:uid:prometheus-uid
list_prometheus_label_valuesPrometheusПеречислить значения для конкретной меткиdatasources:querydatasources:uid:prometheus-uid
query_prometheus_histogramPrometheusРассчитать значения процентилей гистограммыdatasources:querydatasources:uid:prometheus-uid
list_incidentsIncidentПеречислить инциденты в Grafana IncidentРоль просмотраН/Д
create_incidentIncidentСоздать инцидент в Grafana IncidentРоль редактораН/Д
add_activity_to_incidentIncidentДобавить элемент активности в инцидент в Grafana IncidentРоль редактораН/Д
get_incidentIncidentПолучить один инцидент по IDРоль просмотраН/Д
query_loki_logsLokiЗапросить и получить логи с помощью LogQL (запросы логов или метрик)datasources:querydatasources:uid:loki-uid
list_loki_label_namesLokiПеречислить все доступные имена меток в логахdatasources:querydatasources:uid:loki-uid
list_loki_label_valuesLokiПеречислить значения для конкретной метки логаdatasources:querydatasources:uid:loki-uid
query_loki_statsLokiПолучить статистику о потоках логовdatasources:querydatasources:uid:loki-uid
query_loki_patternsLokiВыполнить запрос обнаруженных шаблонов логов для выявления общих структурdatasources:querydatasources:uid:loki-uid
analyze_loki_labelsLokiПроверить стратегию меток Loki (динамическую или статическую) и при необходимости диагностировать производительность запросовdatasources:querydatasources:uid:loki-uid
suggest_loki_alloy_label_configConfigСгенерировать фрагмент loki.process Alloy, обеспечивающий соблюдение утверждённых метокН/ДН/Д
query_influxdbInfluxDBЗапросить InfluxDB с помощью InfluxQL (v1) или Flux (v2)datasources:querydatasources:uid:influxdb-uid
list_clickhouse_tablesClickHouse*Перечислить таблицы в базе данных ClickHousedatasources:querydatasources:uid:*
describe_clickhouse_tableClickHouse*Получить схему таблицы с типами столбцовdatasources:querydatasources:uid:*
query_clickhouseClickHouse*Выполнить SQL-запросы с подстановкой макросовdatasources:querydatasources:uid:*
list_cloudwatch_namespacesCloudWatch*Перечислить доступные пространства имён AWS CloudWatchdatasources:querydatasources:uid:*
list_cloudwatch_metricsCloudWatch*Список метрик в пространстве имёнdatasources:querydatasources:uid:*
list_cloudwatch_dimensionsCloudWatch*Список измерений для метрикиdatasources:querydatasources:uid:*
query_cloudwatchCloudWatch*Выполнение запросов к метрикам CloudWatchdatasources:querydatasources:uid:*
list_athena_catalogsAthena*Список доступных каталогов данных Athenadatasources:querydatasources:uid:*
list_athena_databasesAthena*Список баз данных в каталоге Athenadatasources:querydatasources:uid:*
list_athena_tablesAthena*Список таблиц в базе данных Athenadatasources:querydatasources:uid:*
describe_athena_tableAthena*Получение имён столбцов для таблицы Athenadatasources:querydatasources:uid:*
query_athenaAthena*Выполнение SQL-запросов с подстановкой макросовdatasources:querydatasources:uid:*
query_elasticsearchElasticsearch/OpenSearch*Запрос к Elasticsearch или OpenSearch с использованием синтаксиса Lucene или Query DSLdatasources:querydatasources:uid:datasource-uid
query_quickwitQuickwit*Запрос к Quickwit с использованием синтаксиса Lucene или Query DSLdatasources:querydatasources:uid:quickwit-uid
list_snowflake_tablesSnowflake*Список таблиц в базе данных/схеме Snowflake через INFORMATION_SCHEMAdatasources:querydatasources:uid:*
describe_snowflake_tableSnowflake*Получение схемы таблицы (типы столбцов, допустимость NULL, значения по умолчанию, комментарии)datasources:querydatasources:uid:*
query_snowflakeSnowflake*Выполнение SQL-запросов с подстановкой макросов/переменныхdatasources:querydatasources:uid:*
alerting_manage_rulesAlertingУправление правилами оповещений (список, получение, версии, создание, обновление, удаление)alert.rules:read + alert.rules:write для измененийfolders:* или folders:uid:alerts-folder
alerting_manage_routingAlertingУправление политиками уведомлений, контактными точками и временными интерваламиalert.notifications:readГлобальная область видимости
list_oncall_schedulesOnCallСписок расписаний из Grafana OnCallgrafana-oncall-app.schedules:readОбласти видимости, специфичные для плагина
get_oncall_shiftOnCallПолучение подробной информации о конкретной смене OnCallgrafana-oncall-app.schedules:readОбласти видимости, специфичные для плагина
get_current_oncall_usersOnCallПолучение пользователей, находящихся на дежурстве для конкретного расписанияgrafana-oncall-app.schedules:readОбласти видимости, специфичные для плагина
list_oncall_teamsOnCallСписок команд из Grafana OnCallgrafana-oncall-app.user-settings:readОбласти видимости, специфичные для плагина
list_oncall_usersOnCallСписок пользователей из Grafana OnCallgrafana-oncall-app.user-settings:readОбласти видимости, специфичные для плагина
list_alert_groupsOnCallСписок групп алертов из Grafana OnCall с параметрами фильтрацииgrafana-oncall-app.alert-groups:readОбласти видимости, специфичные для плагина
get_alert_groupOnCallПолучение конкретной группы алертов из Grafana OnCall по её идентификаторуgrafana-oncall-app.alert-groups:readОбласти видимости, специфичные для плагина
get_sift_investigationSiftПолучение существующего расследования Sift по его UUIDРоль ViewerНе применимо
get_sift_analysisSiftПолучение конкретного анализа из расследования SiftРоль ViewerНе применимо
list_sift_investigationsSiftПолучение списка расследований Sift с необязательным ограничениемРоль ViewerНе применимо
find_error_pattern_logsSiftПоиск повышенных паттернов ошибок в журналах Loki.Роль EditorНе применимо
find_slow_requestsSiftПоиск медленных запросов в соответствующих источниках данных tempo.Роль EditorНе применимо
list_pyroscope_label_namesPyroscopeСписок имён меток, соответствующих селекторуdatasources:querydatasources:uid:pyroscope-uid
list_pyroscope_label_valuesPyroscopeСписок значений меток, соответствующих селектору для имени меткиdatasources:querydatasources:uid:pyroscope-uid
list_pyroscope_profile_typesPyroscopeСписок доступных типов профилейdatasources:querydatasources:uid:pyroscope-uid
query_pyroscopePyroscopeЗапрос профилей, метрик или того и другого из Pyroscopedatasources:querydatasources:uid:pyroscope-uid
get_assertionsAssertsПолучение сводки утверждений для заданной сущностиРазрешения, специфичные для плагинаОбласти видимости, специфичные для плагина
agento11y_manage_conversationsAgent Observability*Список, поиск и получение LLM-диалогов из Grafana Agent Observabilitygrafana-agento11y-app.conversations:readНе применимо
agento11y_manage_generationsAgent Observability*Получение деталей генерации LLM и оценок из Grafana Agent Observabilitygrafana-agento11y-app.data:readНе применимо
agento11y_manage_agentsAgent Observability*Чтение каталога агентов: список агентов, полная версия одного агента, история версий и агрегированные оценки по версиямgrafana-agento11y-app.data:readНе применимо
agento11y_manage_evaluatorsAgent Observability*Управление оценщиками, шаблонами оценщиков и каталогом судей (список, получение, upsert, форк, тест, удаление)grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write для изменений и тестовНе применимо
agento11y_manage_eval_rulesAgent Observability*Управление правилами оценки и защитными механизмами (список, получение, создание, обновление, предпросмотр, удаление)grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write для изменений и предпросмотровНе применимо
agento11y_manage_eval_collectionsAgent Observability*Управление сохранёнными диалогами и коллекциями, которые их группируют (список, получение, сохранение, создание, обновление, удаление, добавление и удаление участников)grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write для измененийНе применимо
agento11y_manage_experimentsAgent Observability*Чтение офлайн-экспериментов, их испытаний, оценок, метаданных артефактов и фильтров; обновление и отмена экспериментаgrafana-agento11y-app.data:read + grafana-agento11y-app.eval:write для измененийНе применимо
agento11y_manage_test_suitesAgent Observability*Управление тестовыми наборами, используемыми офлайн-экспериментами, их версиями и тестовыми случаями (список, получение, создание, обновление, черновик, публикация, upsert, удаление)grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write для измененийНе применимо
ask_assistantAssistant*Отправка запроса в Grafana Assistant и получение полного текстового ответа (многосессионный режим через contextId)Разрешения, специфичные для плагинаОбласти видимости, специфичные для плагина
generate_deeplinkNavigationГенерация точных deep-link URL для ресурсов GrafanaНет (только генерация URL на чтение)Не применимо
get_annotationsAnnotationsПолучение аннотаций с фильтрамиannotations:readannotations:* или annotations:id:123
create_annotationАннотацииСоздать новую аннотацию (стандартный формат или формат Graphite)annotations:writeannotations:*
update_annotationАннотацииОбновить определенные поля аннотации (частичное обновление)annotations:writeannotations:*
get_annotation_tagsАннотацииСписок тегов аннотаций с необязательной фильтрациейannotations:readannotations:*
list_snapshotsСнимокСписок снимков дашбордов с необязательными фильтрами запроса и лимитаdashboards:readdashboards:* или dashboards:uid:abc123
get_snapshotСнимокПолучить метаданные снимка и полезную нагрузку дашборда по ключу снимкаdashboards:readdashboards:* или dashboards:uid:abc123
create_snapshotСнимокСоздать снимок дашборда из полной полезной нагрузки дашбордаdashboards:writedashboards:* или dashboards:uid:abc123
delete_snapshotСнимокУдалить снимок дашборда по ключу снимкаdashboards:writedashboards:* или dashboards:uid:abc123
get_panel_imageРендерингРендерить сохраненный дашборд или панель — или предварительный просмотр провижининга из ветки репозитория — в виде PNG-изображенияdashboards:readdashboards:uid:abc123
list_provisioning_repositoriesПровижинингСписок репозиториев провижининга (например, источников git-sync) с их URL-адресом источника, веткой, состоянием синхронизации и работоспособностьюprovisioning.repositories:readN/A
validate_provisioning_fileПровижинингПрименить файл из репозитория провижининга в режиме пробного запуска и сообщить об ошибках проверки допускаprovisioning.repositories:readN/A
  • Отключено по умолчанию. Добавьте категорию в --enabled-tools, чтобы включить.*

Справочник флагов CLI

Бинарный файл mcp-grafana поддерживает различные флаги командной строки для настройки:

Параметры транспорта:

  • -t, --transport: Тип транспорта (stdio, sse или streamable-http) — по умолчанию: stdio
  • --address: Хост и порт для SSE/streamable-http сервера — по умолчанию: localhost:8000
  • --base-path: Базовый путь для SSE/streamable-http сервера
  • --endpoint-path: Путь конечной точки для streamable-http сервера — по умолчанию: /mcp
  • --server-name: Имя сервера, используемое в рукопожатии MCP и OTel service.name — по умолчанию: mcp-grafana. Переопределяет переменную окружения GRAFANA_MCP_SERVER_NAME

Безопасность HTTP-транспорта (только SSE / streamable-http):

Проверка Host/Origin применяется на каждом маршруте слушателя — /sse, /mcp, /healthz и /metrics — поэтому браузер с DNS-ребinding не может получить доступ ни к одному из них. Stdio-транспорт не затрагивается.

  • --allowed-hosts: Разделённый запятыми список разрешённых значений заголовка Host. По умолчанию используются варианты loopback для --address (например, localhost:8000,127.0.0.1:8000,[::1]:8000). Значение, которое преобразуется в пустое (не задано, ,, , и т. д.), также возвращается к значениям по умолчанию, чтобы опечатка не могла незаметно отключить проверку. Запросы с заголовком Host вне списка разрешённых отклоняются с кодом 403. Передайте *, чтобы отключить проверку — это безопасно только при работе за доверенным обратным прокси, который перезаписывает Host, или в изолированной сети. K8s httpGet пробы и внешние /metrics сборы метрик потребуют либо явного имени хоста в этом списке, *, либо tcpSocket пробы / отдельного порта метрик (--metrics-address).
  • --allowed-origins: Разделённый запятыми список разрешённых значений заголовка Origin. По умолчанию пусто — любой запрос, содержащий заголовок Origin, отклоняется (браузеры всегда отправляют его для межсайтовых запросов, и ни один браузер не должен вызывать этот сервер напрямую). Укажите явный список, чтобы разрешить браузерным клиентам, или *, чтобы отключить проверку.

Аутентификация вызывающего (только SSE / streamable-http):

При необходимости требуйте от MCP-клиентов аутентификацию на сервере. Это отдельно от учётных данных, которые сервер использует для доступа к Grafana. Stdio не затрагивается.

  • --server-auth-token: Bearer-токен, который вызывающие должны отправлять как Authorization: Bearer <token>. Возвращается к переменной окружения MCP_GRAFANA_SERVER_TOKEN. Если задан, запросы без действительного токена отклоняются с кодом 401 до выполнения любых инструментов. Предпочтительнее использовать переменную окружения, чтобы секрет не был виден в аргументах процесса.

Аутентификация вызывающего применяется только когда задан --server-auth-token. Когда он не задан и сервер привязывается к адресу, отличному от loopback, сервер запускается, но регистрирует ошибку безопасности — выводится на уровне журнала error, чтобы не скрываться уровнем --log-level (loopback и stdio не затрагиваются); в будущем крупном релизе это станет ошибкой запуска. Используйте TLS (или терминацию TLS) всякий раз, когда аутентификация вызывающего включена на адресе, отличном от loopback. Когда аутентификация вызывающего включена, проверенный заголовок Authorization удаляется до того, как запросы достигнут Grafana; комбинация --server-auth-token с GRAFANA_FORWARD_HEADERS=Authorization отклоняется при запуске.

Отладка и журналирование:

  • --debug: Включить режим отладки для подробного журналирования HTTP-запросов/ответов
  • --log-level: Уровень журнала (debug, info, warn, error) — по умолчанию: info

Параметры клиента Grafana:

  • --grafana-timeout: Лимит времени для запросов, выполняемых клиентом Grafana. Принимает строки длительности Go (например, 10s, 500ms) — по умолчанию: 10s
  • --include-args-in-spans: Включать аргументы вызовов инструментов в спаны OpenTelemetry. Включайте только в непроизводственных средах или когда известно, что аргументы не содержат PII — по умолчанию: false

Наблюдаемость:

  • --metrics: Включить конечную точку метрик Prometheus на /metrics
  • --metrics-address: Отдельный адрес для сервера метрик (например, :9090). Если пусто, метрики обслуживаются на основном сервере
  • --slow-request-threshold: Регистрировать событие, когда любой MCP-запрос (вызов инструмента, список, чтение ресурса и т. д.) занимает дольше этого времени. Принимает строки длительности Go (например, 500ms, 5s). По умолчанию 0 отключает журналирование медленных запросов. См. раздел Журналирование медленных запросов.
  • --slow-request-log-level: Уровень журнала для событий медленных запросов (info или warn) — по умолчанию: warn.

Управление сессиями:

  • --session-idle-timeout-minutes: Тайм-аут бездействия сессии в минутах. Сессии без активности в течение этого времени автоматически удаляются — по умолчанию: 30. Установите 0, чтобы отключить удаление сессий. Актуально только для SSE и streamable-http транспортов.

Конфигурация инструментов:

  • --enabled-tools: Разделённый запятыми список включённых категорий — по умолчанию: все категории, кроме admin, agento11y, assistant, athena, clickhouse, cloudwatch, elasticsearch, examples, graphite, quickwit, runpanelquery и snowflake. Чтобы включить отключённые категории, добавьте их в список (например, "search,datasource,...,snowflake")
  • --max-loki-log-limit: Максимальное количество строк журнала, возвращаемых за один вызов query_loki_logs — по умолчанию: 100. Примечание: Установите это значение минимум на 1 ниже серверного max_entries_limit_per_query Loki, чтобы обеспечить обнаружение усечения (инструмент внутренне запрашивает limit+1, чтобы определить, существуют ли дополнительные данные).
  • --disable-search: Отключить инструменты поиска
  • --disable-datasource: Отключить инструменты источников данных
  • --disable-incident: Отключить инструменты инцидентов
  • --disable-prometheus: Отключить инструменты Prometheus
  • --disable-write: Отключить инструменты записи (операции создания/обновления)
  • --disable-loki: Отключить инструменты Loki
  • --disable-elasticsearch: Отключить инструменты Elasticsearch и OpenSearch
  • --disable-quickwit: Отключить инструменты Quickwit
  • --disable-influxdb: Отключить инструменты InfluxDB
  • --disable-alerting: Отключить инструменты оповещения
  • --disable-dashboard: Отключить инструменты панелей
  • --disable-oncall: Отключить инструменты OnCall
  • --disable-asserts: Отключить инструменты Asserts
  • --disable-sift: Отключить инструменты Sift
  • --disable-admin: Отключить инструменты администрирования
  • --disable-pyroscope: Отключить инструменты Pyroscope
  • --disable-navigation: Отключить инструменты навигации
  • --disable-rendering: Отключить инструменты рендеринга (экспорт изображений панелей/панелей)
  • --disable-snapshot: Отключить инструменты снимков
  • --disable-cloudwatch: Отключить инструменты CloudWatch
  • --disable-examples: Отключить инструменты примеров запросов
  • --disable-clickhouse: Отключить инструменты ClickHouse
  • --disable-snowflake: Отключить инструменты Snowflake
  • --disable-runpanelquery: Отключить инструменты выполнения запросов панелей
  • --disable-graphite: Отключить инструменты Graphite
  • --disable-athena: Отключить инструменты Athena
  • --disable-provisioning: Отключить инструменты подготовки (provisioning)
  • --disable-agento11y: Отключить инструменты наблюдаемости агента (Agent Observability)
  • --disable-assistant: Отключить инструменты Grafana Assistant

Режим только для чтения

Флаг --disable-write предоставляет способ запуска MCP-сервера в режиме только для чтения, предотвращая любые операции записи в ваш экземпляр Grafana. Это полезно в сценариях, где требуется предоставить безопасный доступ только для чтения, например:

  • Использование сервисных учётных записей с ограниченными правами только для чтения
  • Предоставление AI-ассистентам данных наблюдаемости без возможности изменения
  • Работа в производственных средах, где доступ на запись должен быть ограничен
  • Сценарии тестирования и разработки, где нужно предотвратить случайные изменения

Когда --disable-write включён, следующие операции записи отключаются:

Инструменты панелей:

  • update_dashboard

Инструменты папок:

  • create_folder

Инструменты инцидентов:

  • create_incident
  • add_activity_to_incident

Инструменты оповещения:

  • alerting_manage_rules (операции создания, обновления, удаления)

Инструменты аннотаций:

  • create_annotation
  • update_annotation

Инструменты Sift:

  • find_error_pattern_logs (создаёт расследования)
  • find_slow_requests (создаёт расследования)

Инструменты снимков:

  • create_snapshot
  • delete_snapshot

Инструменты наблюдаемости агента (Agent Observability):

  • agento11y_manage_evaluators (операции upsert, delete, fork, test evaluator)
  • agento11y_manage_eval_rules (операции создания, обновления, удаления, предпросмотра правил и guard)
  • agento11y_manage_eval_collections (сохранение и удаление сохранённых бесед; создание, обновление, удаление коллекций; добавление и удаление участников коллекций)
  • agento11y_manage_experiments (операции обновления и отмены экспериментов)
  • agento11y_manage_test_suites (создание и обновление тестовых наборов; создание и публикация версий; upsert и удаление тестовых случаев)

Все операции чтения остаются доступными, что позволяет запрашивать панели, выполнять запросы PromQL/LogQL, перечислять ресурсы и получать данные.

Конфигурация TLS клиента (для подключений к Grafana):

  • --tls-cert-file: Путь к файлу TLS-сертификата для аутентификации клиента
  • --tls-key-file: Путь к файлу TLS-приватного ключа для аутентификации клиента
  • --tls-ca-file: Путь к файлу CA-сертификата TLS для проверки сервера
  • --tls-skip-verify: Пропустить проверку TLS-сертификата (небезопасно)

Конфигурация TLS сервера (только transport streamable-http):

  • --server.tls-cert-file: Путь к файлу TLS-сертификата для HTTPS сервера
  • --server.tls-key-file: Путь к файлу TLS-приватного ключа для HTTPS сервера

Использование

Этот MCP-сервер работает как с локальными экземплярами Grafana, так и с Grafana Cloud. Для Grafana Cloud используйте URL вашего экземпляра (например, https://myinstance.grafana.net) вместо http://localhost:3000 в примерах конфигурации ниже.

  1. Если вы используете аутентификацию через токен сервисной учётной записи, создайте сервисную учётную запись в Grafana с достаточными правами для использования нужных инструментов, сгенерируйте токен сервисной учётной записи и скопируйте его в буфер обмена для использования в файле конфигурации. Следуйте документации Grafana по сервисным учётным записям для получения подробной информации о создании токенов сервисных учётных записей. Совет: Если вам неудобно настраивать детальные RBAC-области, более простой (но менее ограничивающий) вариант — назначить сервисной учётной записи встроенную роль Editor. Это предоставляет широкий доступ на чтение/запись, который покрывает большинство операций MCP-сервера — используйте её, когда удобство важнее строгих требований минимальных привилегий.

    Примечание: Переменная окружения GRAFANA_API_KEY устарела и будет удалена в будущей версии. Перейдите на использование GRAFANA_SERVICE_ACCOUNT_TOKEN. Старое имя переменной продолжит работать для обратной совместимости, но будет показывать предупреждения об устаревании.

Чтение токена сервисной учётной записи из файла

Вместо передачи токена инлайн через GRAFANA_SERVICE_ACCOUNT_TOKEN, вы можете указать GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE на путь к файлу, содержащему токен. Файл читается заново при каждом запросе, поэтому ротированные токены подхватываются автоматически без перезапуска сервера.

Это особенно полезно в Kubernetes, где Secret, смонтированный как том, обновляется на месте при изменении базового Secret (обычно в течение ~1 минуты). В сочетании с клиентским кэшем на каждый запрос — который использует значение токена как ключ — ротированный токен прозрачно создаёт нового клиента без перезапуска pod и без простоев:

env:
  - name: GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE
    value: /var/run/secrets/grafana/token
volumeMounts:
  - name: grafana-token
    mountPath: /var/run/secrets/grafana
    readOnly: true
volumes:
  - name: grafana-token
    secret:
      secretName: grafana-mcp-token

Окружающие пробелы (включая завершающий перевод строки) обрезаются из содержимого файла. Если заданы и GRAFANA_SERVICE_ACCOUNT_TOKEN, и GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE, инлайн-токен имеет приоритет.

Поддержка нескольких организаций

Вы можете указать, с какой организацией взаимодействовать, используя либо:

  • Переменную окружения: Установите GRAFANA_ORG_ID в числовой идентификатор организации
  • HTTP-заголовок: Установите X-Grafana-Org-Id при использовании SSE или streamable HTTP транспортов (заголовок имеет приоритет над переменной окружения — это также позволяет задать организацию по умолчанию).

Когда указан идентификатор организации, MCP-сервер будет устанавливать заголовок X-Grafana-Org-Id на все запросы к Grafana, обеспечивая выполнение операций в контексте указанной организации.

Пример с идентификатором организации:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_USERNAME": "<your username>",
        "GRAFANA_PASSWORD": "<your password>",
        "GRAFANA_ORG_ID": "2"
      }
    }
  }
}

Настраиваемые HTTP-заголовки

Вы можете добавлять произвольные HTTP-заголовки ко всем запросам к API Grafana, используя переменную окружения GRAFANA_EXTRA_HEADERS. Значение должно быть JSON-объектом, сопоставляющим имена заголовков со значениями.

Пример с пользовательскими заголовками:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your token>",
        "GRAFANA_EXTRA_HEADERS": "{\"X-Custom-Header\": \"custom-value\", \"X-Tenant-ID\": \"tenant-123\"}"
      }
    }
  }
}

Пересылка заголовков от клиента (только SSE/Streamable-HTTP)

Когда MCP-сервер работает за шлюзом или обратным прокси, который обрабатывает SSO (например, AWS ALB с OIDC), файл cookie сеанса каждого пользователя должен достигать Grafana, чтобы она могла связать запрос с аутентифицированным пользователем. Переменная окружения GRAFANA_FORWARD_HEADERS включает это, задавая разделённый запятыми список разрешённых имён заголовков для копирования из входящего HTTP-запроса в каждый исходящий запрос к API Grafana.

Это применимо только при использовании транспортов SSE (-t sse) или streamable-http (-t streamable-http). В режиме stdio это не действует.

Пример: пересылка файла cookie сеанса

{
  "env": {
    "GRAFANA_URL": "https://grafana.internal",
    "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your token>",
    "GRAFANA_FORWARD_HEADERS": "Cookie"
  }
}

Вы можете пересылать несколько заголовков, разделяя их запятыми:

GRAFANA_FORWARD_HEADERS=Cookie,X-Session-Id

Пересылаемые заголовки объединяются с любыми заголовками, определёнными в GRAFANA_EXTRA_HEADERS. Если имя заголовка встречается в обоих местах, значение из входящего запроса имеет приоритет для этого запроса.

  1. У вас есть несколько вариантов установки mcp-grafana:

    • uvx (рекомендуется): Если у вас установлен uv, дополнительная настройка не требуется — uvx автоматически загрузит и запустит сервер:

      uvx mcp-grafana

    • Образ Docker: Используйте готовый образ Docker из Docker Hub.

      Важно: Точка входа образа Docker настроена на запуск MCP-сервера в режиме SSE по умолчанию, но большинство пользователей захотят использовать режим STDIO для прямой интеграции с ИИ-ассистентами, такими как Claude Desktop:

      1. Режим STDIO: Для режима stdio вы должны явно переопределить значение по умолчанию с помощью -t stdio и включить флаг -i, чтобы оставить stdin открытым:
      docker pull grafana/mcp-grafana
# For local Grafana:
docker run --rm -i -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio
# For Grafana Cloud:
docker run --rm -i -e GRAFANA_URL=https://myinstance.grafana.net -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio

      Примечание — защита сетевых режимов: В режимах SSE и streamable-http контейнер привязывается к не-loopback адресу (0.0.0.0:8000). Без токена вызывающего сервер запускается, но регистрирует ошибку безопасности (на уровне журнала error, поэтому она не скрывается параметром --log-level; и в будущем крупном релизе он откажется запускаться). Установите MCP_GRAFANA_SERVER_TOKEN, чтобы требовать Authorization: Bearer <token> от клиентов (рекомендуется). Режим STDIO не затрагивается. См. Аутентификация вызывающего.

      1. Режим SSE: В этом режиме сервер работает как HTTP-сервер, к которому подключаются клиенты. Вы должны открыть порт 8000 с помощью флага -p:
      docker pull grafana/mcp-grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> grafana/mcp-grafana
      1. Режим Streamable HTTP: В этом режиме сервер работает как независимый процесс, который может обрабатывать несколько клиентских подключений. Вы должны открыть порт 8000 с помощью флага -p: Для этого режима вы должны явно переопределить значение по умолчанию с помощью -t streamable-http
      docker pull grafana/mcp-grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> grafana/mcp-grafana -t streamable-http

      Для режима HTTPS streamable HTTP с сертификатами TLS сервера:

      docker pull grafana/mcp-grafana
docker run --rm -p 8443:8443 \
  -v /path/to/certs:/certs:ro \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
  -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> \
  grafana/mcp-grafana \
  -t streamable-http \
  -addr :8443 \
  --server.tls-cert-file /certs/server.crt \
  --server.tls-key-file /certs/server.key

    • Скачать бинарный файл: Скачайте последний релиз mcp-grafana со страницы релизов и поместите его в ваш $PATH.

    • Сборка из исходников: Если у вас установлен инструментарий Go, вы также можете собрать и установить его из исходников, используя переменную окружения GOBIN для указания каталога, куда должен быть установлен бинарный файл. Он также должен находиться в вашем $PATH.

      GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest

    • Развертывание в Kubernetes с помощью Helm: используйте Helm-чарт из репозитория Grafana helm-charts

      helm repo add grafana https://grafana.github.io/helm-charts
helm install --set grafana.apiKey=<Grafana_ApiKey> --set grafana.url=<GrafanaUrl> my-release grafana/grafana-mcp

  2. Добавьте конфигурацию сервера в файл конфигурации вашего клиента. Например, для Claude Desktop:

    Если используется uvx:

    {
  "mcpServers": {
    "grafana": {
      "command": "uvx",
      "args": ["mcp-grafana"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

    Если используется бинарный файл:

    {
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>",
        // If using username/password authentication
        "GRAFANA_USERNAME": "<your username>",
        "GRAFANA_PASSWORD": "<your password>",
        // Optional: specify organization ID for multi-org support
        "GRAFANA_ORG_ID": "1"
      }
    }
  }
}

Примечание: если вы видите Error: spawn mcp-grafana ENOENT в Claude Desktop, вам нужно указать полный путь к mcp-grafana.

Если используется Docker:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio"
      ],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>",
        // If using username/password authentication
        "GRAFANA_USERNAME": "<your username>",
        "GRAFANA_PASSWORD": "<your password>",
        // Optional: specify organization ID for multi-org support
        "GRAFANA_ORG_ID": "1"
      }
    }
  }
}

Примечание: Аргумент -t stdio здесь важен, потому что он переопределяет режим SSE по умолчанию в образе Docker.

Использование VSCode с удалённым MCP-сервером

Если вы используете VSCode и запускаете MCP-сервер в режиме SSE (который используется по умолчанию при использовании образа Docker без переопределения транспорта), убедитесь, что ваш .vscode/settings.json включает следующее:

"mcp": {
  "servers": {
    "grafana": {
      "type": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

Для режима HTTPS streamable HTTP с сертификатами TLS сервера:

"mcp": {
  "servers": {
    "grafana": {
      "type": "sse",
      "url": "https://localhost:8443/sse"
    }
  }
}

Режим отладки

Вы можете включить режим отладки для транспорта Grafana, добавив флаг -debug в команду. Это обеспечит подробное журналирование HTTP-запросов и ответов между MCP-сервером и API Grafana, что может быть полезно для устранения неполадок.

Чтобы использовать режим отладки с конфигурацией Claude Desktop, обновите конфигурацию следующим образом:

Если используется бинарный файл:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": ["-debug"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Если используется Docker:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio",
        "-debug"
      ],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Примечание: Как и в стандартной конфигурации, аргумент -t stdio требуется для переопределения режима SSE по умолчанию в образе Docker.

Конфигурация TLS

Если ваш экземпляр Grafana находится за mTLS или требует пользовательских сертификатов TLS, вы можете настроить MCP-сервер на использование пользовательских сертификатов. Сервер поддерживает следующие параметры конфигурации TLS:

  • --tls-cert-file: Путь к файлу сертификата TLS для аутентификации клиента
  • --tls-key-file: Путь к файлу закрытого ключа TLS для аутентификации клиента
  • --tls-ca-file: Путь к файлу сертификата ЦС TLS для проверки сервера
  • --tls-skip-verify: Пропустить проверку сертификата TLS (небезопасно, используйте только для тестирования)

Пример с аутентификацией по клиентскому сертификату:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [
        "--tls-cert-file",
        "/path/to/client.crt",
        "--tls-key-file",
        "/path/to/client.key",
        "--tls-ca-file",
        "/path/to/ca.crt"
      ],
      "env": {
        "GRAFANA_URL": "https://secure-grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Пример с Docker:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/path/to/certs:/certs:ro",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio",
        "--tls-cert-file",
        "/certs/client.crt",
        "--tls-key-file",
        "/certs/client.key",
        "--tls-ca-file",
        "/certs/ca.crt"
      ],
      "env": {
        "GRAFANA_URL": "https://secure-grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Конфигурация TLS применяется ко всем HTTP-клиентам, используемым MCP-сервером, включая:

  • Основной клиент Grafana OpenAPI
  • Клиенты источников данных Prometheus
  • Клиенты источников данных Loki
  • Клиенты управления инцидентами
  • Клиенты расследований Sift
  • Клиенты оповещений
  • Клиенты Asserts

Примеры прямого использования CLI:

Для тестирования с самоподписанными сертификатами:

./mcp-grafana --tls-skip-verify -debug

С аутентификацией по клиентскому сертификату:

./mcp-grafana \
  --tls-cert-file /path/to/client.crt \
  --tls-key-file /path/to/client.key \
  --tls-ca-file /path/to/ca.crt \
  -debug

Только с пользовательским сертификатом ЦС:

./mcp-grafana --tls-ca-file /path/to/ca.crt

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

Если вы используете эту библиотеку программно, вы также можете создавать функции контекста с поддержкой TLS:

// Using struct literals
tlsConfig := &mcpgrafana.TLSConfig{
    CertFile: "/path/to/client.crt",
    KeyFile:  "/path/to/client.key",
    CAFile:   "/path/to/ca.crt",
}
grafanaConfig := mcpgrafana.GrafanaConfig{
    Debug:     true,
    TLSConfig: tlsConfig,
}
contextFunc := mcpgrafana.ComposedStdioContextFunc(grafanaConfig)

// Or inline
grafanaConfig := mcpgrafana.GrafanaConfig{
    Debug: true,
    TLSConfig: &mcpgrafana.TLSConfig{
        CertFile: "/path/to/client.crt",
        KeyFile:  "/path/to/client.key",
        CAFile:   "/path/to/ca.crt",
    },
}
contextFunc := mcpgrafana.ComposedStdioContextFunc(grafanaConfig)

Проверка URL:

При прямом вызове NewGrafanaClient (stdio или программное создание) предварительно проверяйте URL, чтобы избежать достижимой паники:

if err := mcpgrafana.ValidateGrafanaURL(urlFromHeader); err != nil {
    http.Error(w, err.Error(), http.StatusBadRequest)
    return
}
client := mcpgrafana.NewGrafanaClient(ctx, urlFromHeader, apiKey, nil)

Конфигурация TLS сервера (только для транспорта Streamable HTTP)

При использовании транспорта streamable HTTP (-t streamable-http) вы можете настроить MCP-сервер на обслуживание HTTPS вместо HTTP. Это полезно, когда вам нужно защитить соединение между вашим MCP-клиентом и самим сервером.

Сервер поддерживает следующие параметры конфигурации TLS для транспорта streamable HTTP:

  • --server.tls-cert-file: Путь к файлу сертификата TLS для HTTPS сервера (обязательно для TLS)
  • --server.tls-key-file: Путь к файлу закрытого ключа TLS для HTTPS сервера (обязательно для TLS)

Примечание: Эти флаги полностью отделены от флагов TLS клиента, описанных выше. Флаги TLS клиента настраивают, как MCP-сервер подключается к Grafana, в то время как эти флаги TLS сервера настраивают, как клиенты подключаются к MCP-серверу при использовании транспорта streamable HTTP.

Пример с HTTPS streamable HTTP сервером:

./mcp-grafana \
  -t streamable-http \
  --server.tls-cert-file /path/to/server.crt \
  --server.tls-key-file /path/to/server.key \
  -addr :8443

Это запустит MCP-сервер на HTTPS-порту 8443. Клиенты затем будут подключаться к https://localhost:8443/ вместо http://localhost:8000/.

Пример Docker с TLS сервера:

docker run --rm -p 8443:8443 \
  -v /path/to/certs:/certs:ro \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
  grafana/mcp-grafana \
  -t streamable-http \
  -addr :8443 \
  --server.tls-cert-file /certs/server.crt \
  --server.tls-key-file /certs/server.key

Конечная точка проверки работоспособности

При использовании транспортов SSE (-t sse) или streamable HTTP (-t streamable-http) MCP-сервер предоставляет конечную точку проверки работоспособности по адресу /healthz. Эта конечная точка может использоваться балансировщиками нагрузки, системами мониторинга или платформами оркестрации для проверки того, что сервер работает и принимает соединения.

Конечная точка: GET /healthz

Ответ:

  • Код состояния: 200 OK
  • Тело: ok

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

# For streamable HTTP or SSE transport on default port
curl http://localhost:8000/healthz

# With custom address
curl http://localhost:9090/healthz

Примечание: Конечная точка проверки работоспособности доступна только при использовании транспортов SSE или streamable HTTP. Она недоступна при использовании транспорта stdio (-t stdio), так как stdio не предоставляет HTTP-сервер.

Наблюдаемость

MCP-сервер поддерживает метрики Prometheus, распределённую трассировку OpenTelemetry и экспорт журналов OpenTelemetry, следуя семантическим соглашениям OTel MCP. Трассировка и экспорт журналов настраиваются через стандартные переменные окружения OTEL_* и работают с любым транспортом.

Примечание: mcp-grafana в настоящее время поддерживает только транспорт OTLP/gRPC как для трассировок, так и для журналов. OTEL_EXPORTER_OTLP_PROTOCOL (и его варианты _TRACES_PROTOCOL / _LOGS_PROTOCOL) не учитываются — gRPC используется в любом случае.

Метрики

При использовании транспортов SSE или streamable HTTP включите метрики Prometheus с помощью флага --metrics:

# Metrics served on the main server at /metrics
./mcp-grafana -t streamable-http --metrics

# Metrics served on a separate address
./mcp-grafana -t streamable-http --metrics --metrics-address :9090

Доступные метрики:

МетрикаТипОписание
mcp_server_operation_duration_secondsГистограммаДлительность операций MCP (метки: mcp_method_name, gen_ai_tool_name, error_type, network_transport, mcp_protocol_version)
mcp_server_session_duration_secondsГистограммаДлительность сеансов MCP-клиента (метки: network_transport, mcp_protocol_version)
http_server_request_duration_secondsГистограммаДлительность HTTP-запросов сервера (из otelhttp)

Примечание: Метрики доступны только при использовании транспортов SSE или streamable HTTP. Они недоступны с транспортом stdio.

Журналирование медленных запросов

Флаг --slow-request-threshold генерирует структурированное событие журнала всякий раз, когда запрос MCP (вызов инструмента, список, чтение ресурса и т. д.) превышает заданную длительность. Это полезно для диагностики медленных запросов и вызовов инструментов, не утопая в полном журнале отладки.

# Warn on any request slower than 500ms (works on all transports)
./mcp-grafana -t streamable-http --slow-request-threshold 500ms

# Same thing on stdio (the feature is transport-agnostic, unlike --metrics)
./mcp-grafana -t stdio --slow-request-threshold 500ms

# Log at INFO level instead of WARN (useful during investigation)
./mcp-grafana -t streamable-http --slow-request-threshold 500ms --slow-request-log-level info

Событие журнала содержит следующие структурированные атрибуты:

АтрибутОписание
mcp.methodМетод MCP (например, tools/call, tools/list, resources/read)
durationНаблюдаемая длительность запроса
thresholdНастроенный порог
toolИмя инструмента (присутствует только для методов tools/call)
errorЗначение ошибки, когда запрос не удался (контекст best-effort; содержимое контролируется обёрткой ошибок вышестоящего уровня)
error.typeКлассификация ошибок с ограниченной мощностью (_OTHER для нетипизированных ошибок)

Журналирование медленных запросов работает на всех транспортах (включая stdio) и не требует --metrics. Порог по умолчанию 0 полностью отключает его. Проксируемые инструменты проходят через tools/call и покрываются автоматически.

Трассировка

Распределённая трассировка настраивается через стандартные переменные окружения OTEL_* и работает независимо от флага --metrics. Когда установлен OTEL_EXPORTER_OTLP_ENDPOINT (или специфичный для сигнала OTEL_EXPORTER_OTLP_TRACES_ENDPOINT), сервер экспортирует трассировки через OTLP/gRPC:

# Send traces to a local Tempo instance
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
OTEL_EXPORTER_OTLP_INSECURE=true \
./mcp-grafana -t streamable-http

# Send traces to Grafana Cloud with authentication
OTEL_EXPORTER_OTLP_ENDPOINT=https://tempo-us-central1.grafana.net:443 \
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ..." \
./mcp-grafana -t streamable-http

Спаны вызовов инструментов следуют именованию semconv (tools/call <tool_name>) и включают такие атрибуты, как gen_ai.tool.name, mcp.method.name и mcp.session.id. Сервер также поддерживает распространение контекста трассировки W3C из поля _meta запросов вызова инструментов.

Журналы

Когда установлен OTEL_EXPORTER_OTLP_ENDPOINT (или специфичный для сигнала OTEL_EXPORTER_OTLP_LOGS_ENDPOINT), сервер также экспортирует структурированные журналы через OTLP/gRPC в дополнение к существующему выводу в stderr в виде обычного текста. Мост otelslog автоматически прикрепляет trace_id и span_id из активного спана, поэтому записи журналов коррелируют с трассировками, которые сервер уже отправляет.

Трассировки и журналы разрешают свои конечные точки независимо, поэтому два сигнала могут быть включены отдельно: установка только OTEL_EXPORTER_OTLP_TRACES_ENDPOINT включает трассировку без экспорта журналов, установка только OTEL_EXPORTER_OTLP_LOGS_ENDPOINT включает экспорт журналов без трассировки, а общий OTEL_EXPORTER_OTLP_ENDPOINT включает оба.

Если вы используете общий OTEL_EXPORTER_OTLP_ENDPOINT, но хотите отключить экспорт журналов (например, ваш бэкенд не поддерживает LogsService), установите:

OTEL_LOGS_EXPORTER=none

Это предотвращает создание сервером экспортера журналов OTLP независимо от конфигурации конечной точки, избегая ошибок, подобных unknown service opentelemetry.proto.collector.logs.v1.LogsService.

Логирование в stderr не изменяется при включенном логировании OTLP; вы можете по-прежнему полагаться на логи контейнера или перенаправлять stderr в /dev/null, если предпочитаете.

# Send both logs and traces to a local OTel collector
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
OTEL_EXPORTER_OTLP_INSECURE=true \
./mcp-grafana -t streamable-http

Транспорт — OTLP/gRPC (порт по умолчанию 4317). Журналы можно отправлять напрямую в любой управляемый бэкенд, принимающий OTLP/gRPC — например, Grafana Cloud — указав OTEL_EXPORTER_OTLP_LOGS_ENDPOINT (или общий OTEL_EXPORTER_OTLP_ENDPOINT) на удаленную gRPC-конечную точку и предоставив аутентификацию через OTEL_EXPORTER_OTLP_LOGS_HEADERS (или OTEL_EXPORTER_OTLP_HEADERS), как в примере с трассировкой выше. Локальный коллектор OTel необязателен — полезен для разветвления, пакетной обработки или маршрутизации на несколько бэкендов, но не требуется.

Специфичные для сигналов варианты OTEL_EXPORTER_OTLP_LOGS_ENDPOINT, OTEL_EXPORTER_OTLP_LOGS_HEADERS, OTEL_EXPORTER_OTLP_LOGS_INSECURE, OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE, OTEL_EXPORTER_OTLP_LOGS_TIMEOUT и OTEL_EXPORTER_OTLP_LOGS_COMPRESSION учитываются и переопределяют свои общие аналоги OTEL_EXPORTER_OTLP_* — см. спецификацию экспортера OTel для полного списка и правил приоритета.

Если настроенный коллектор недоступен, записи журналов буферизуются в памяти (очередь по умолчанию: 2048), и при заполнении очереди самые старые записи отбрасываются. Процесс продолжает работу, не блокируя сервис. Настройте локальный коллектор OTel, если вам нужна буферизация без потерь во время сбоев.

Журналы также экспортируются через транспорт stdio, что упрощает централизацию журналов из локальных экземпляров mcp-grafana, вызываемых IDE-клиентами.

Пример Docker с метриками, трассировкой и журналами:

docker run --rm -p 8000:8000 \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your token> \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://tempo:4317 \
  -e OTEL_EXPORTER_OTLP_INSECURE=true \
  grafana/mcp-grafana \
  -t streamable-http --metrics

Устранение неполадок

Совместимость версий Grafana

Если вы столкнулись со следующей ошибкой при использовании инструментов, связанных с источниками данных:

get datasource by uid : [GET /datasources/uid/{uid}][400] getDataSourceByUidBadRequest {"message":"id is invalid"}

Это обычно указывает на то, что вы используете версию Grafana ниже 9.0. Конечная точка API /datasources/uid/{uid} была введена в Grafana 9.0, и операции с источниками данных будут завершаться ошибкой на более ранних версиях.

Решение: Обновите ваш экземпляр Grafana до версии 9.0 или новее, чтобы решить эту проблему.

Разработка

Вклад приветствуется! Пожалуйста, откройте issue или отправьте pull request, если у вас есть предложения или улучшения.

Этот проект написан на Go. Установите Go, следуя инструкциям для вашей платформы.

Чтобы запустить сервер локально в режиме STDIO (который используется по умолчанию для локальной разработки), используйте:

make run

Чтобы запустить сервер локально в режиме SSE, используйте:

go run ./cmd/mcp-grafana --transport sse

Вы также можете запустить сервер с использованием транспорта SSE внутри пользовательского Docker-образа. Как и опубликованный Docker-образ, точка входа этого пользовательского образа по умолчанию использует режим SSE. Чтобы собрать образ, используйте:

make build-image

И чтобы запустить образ в режиме SSE (по умолчанию), используйте:

docker run -it --rm -p 8000:8000 mcp-grafana:latest

Если вам нужно запустить его в режиме STDIO, переопределите настройку транспорта:

docker run -it --rm mcp-grafana:latest -t stdio

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

Доступны три типа тестов:

  1. Модульные тесты (не требуют внешних зависимостей):
make test-unit

Вы также можете запустить модульные тесты с помощью:

make test
  1. Интеграционные тесты (требуют запущенных docker-контейнеров):
make test-integration
  1. Облачные тесты (требуют облачного экземпляра Grafana и учетных данных):
make test-cloud

Примечание: Облачные тесты автоматически настраиваются в CI. Для локальной разработки вам потребуется настроить собственный экземпляр Grafana Cloud и учетные данные.

Более комплексные интеграционные тесты потребуют запущенного локально экземпляра Grafana на порту 3000; вы можете запустить его с помощью Docker Compose:

docker-compose up -d

Интеграционные тесты можно запустить с помощью:

make test-all

Если вы добавляете новые инструменты, пожалуйста, добавьте для них интеграционные тесты. Существующие тесты должны стать хорошей отправной точкой.

Линтинг

Чтобы проверить код, выполните:

make lint

Это включает пользовательский линтер, который проверяет неэкранированные запятые в тегах структур jsonschema. Запятые в полях description должны быть экранированы с помощью \\,, чтобы предотвратить незаметное усечение. Вы можете запустить только этот линтер с помощью:

make lint-jsonschema

См. документацию линтера JSONSchema для получения дополнительных сведений.

Лицензия

Этот проект лицензирован в соответствии с Apache License, Version 2.0.