Сервер MCP для Grafana

Сервер [Протокола контекста модели][mcp] (MCP) для Grafana.

Предоставляет доступ к вашему экземпляру 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-сервере. Этот список носит информационный характер и не является дорожной картой или обязательством по будущим функциям.

Дашборды

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

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

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

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

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

Инструменты для дашбордов теперь включают несколько стратегий для эффективного управления использованием контекста окна (проблема #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, либо Query DSL Elasticsearch. Поддерживает фильтрацию по диапазону времени и извлечение логов, метрик или любых индексированных данных. Возвращает документы с их индексом, ID, полями source и необязательным показателем релевантности.

Запросы к Quickwit

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

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

Инциденты

• Поиск, создание и обновление инцидентов: Управление инцидентами в 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 вместо использования угадывания URL LLM.
• Ссылки на дашборды: Генерация прямых ссылок на дашборды с использованием их 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).
• Обновление аннотации: Замена всех полей существующей аннотации (полное обновление).
• Частичное обновление аннотации (Patch): Обновление только определенных полей аннотации (частичное обновление).
• Получение тегов аннотаций: Вывод списка доступных тегов аннотаций с необязательной фильтрацией.

Снимки

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

Рендеринг

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

Провизионирование

• Список репозиториев провизионирования: Вывод списка репозиториев провизионирования, настроенных для этого экземпляра Grafana (например, источники git-sync), с возвратом slug каждого репозитория, его исходного 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 (Scopes)

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

Распространенные паттерны областей:

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

• 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:* (для создания дашбордов и правил оповещений) 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)

Инструменты