Grafana

MCP-сервер Grafana

MCP-сервер Model Context Protocol для 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 папки, тегу или статусу избранного
• Получение дашборда по UID: получение полной информации о дашборде по его уникальному идентификатору. Передайте необязательный параметр version, чтобы загрузить сохранённый снимок вместо текущего дашборда. Предупреждение: большие дашборды могут занимать значительную часть контекстного окна.
• Список версий дашборда: просмотр сохранённых версий дашборда в виде компактных метаданных (номер версии, автор, временная метка, сообщение о сохранении)
• Сводка по дашборду: получение краткого обзора дашборда, включая название, количество и типы панелей, переменные и метаданные, без полного JSON, чтобы сократить использование контекстного окна
• Получение свойства дашборда: извлечение отдельных частей дашборда с помощью выражений JSONPath (например, $.title, $.panels[*].title), чтобы получать только нужные данные и сокращать использование контекстного окна
• Обновление или создание дашборда: изменение существующих дашбордов или создание новых. Предупреждение: для этого требуется полный JSON дашборда, который может занимать значительную часть контекстного окна.
• Изменение дашборда с помощью патча: внесение отдельных изменений в дашборд без необходимости передавать полный JSON, что значительно сокращает использование контекстного окна при целевых изменениях
• Получение запросов панелей и информации об источниках данных: получение названия, строки запроса и информации об источнике данных (включая UID и тип, если доступны) для каждой панели дашборда

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

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

• Выполнение запроса панели: выполнение запроса панели дашборда с пользовательскими диапазонами времени и переопределениями переменных. Панели Infinity выполняют запросы, если в них используется парсер backend или jq-backend (запросы Google Sheets используют его всегда); парсер simple по умолчанию, а также парсеры UQL и GROQ работают только в браузере. Панели Neo4j в плагине kniepdennis-neo4j-datasource выполняют Cypher-запрос через плагин, который открывает сеансы только для чтения. В панелях Elasticsearch переменные подставляются в запрос Lucene в формате lucene, как это делает Grafana, а автоматические гистограммы дат используют тот же интервал, что и $__interval.

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

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

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

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

• Просмотр списка источников данных и получение информации о них: просмотр всех настроенных источников данных и получение подробной информации о каждом из них.
  • Поддерживаемые типы источников данных: Prometheus, Loki, ClickHouse, CloudWatch, Elasticsearch, OpenSearch, Snowflake, Athena.
• Ресурсы источников данных: каждый доступный вам источник данных также предоставляется как ресурс MCP по адресу grafana://datasources/{uid}, поэтому его можно напрямую прикрепить к беседе (например, с помощью @ в Claude Code), вместо того чтобы модель искала его самостоятельно. Отключается вместе с инструментами для работы с источниками данных.

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

Примечание: инструменты примеров запросов по умолчанию отключены. Чтобы включить их, добавьте 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.

Запросы к источникам данных SQL

Примечание: инструменты SQL по умолчанию отключены. Чтобы включить их, добавьте sql к флагу --enabled-tools. Также работают псевдонимы для обратной совместимости clickhouse, snowflake и athena.

Унифицированные инструменты SQL поддерживают ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, MSSQL и BigQuery в рамках единого набора инструментов. Запросы выполняются через плагины источников данных Grafana, поэтому аутентификация настраивается в источнике данных — учётные данные никогда не передаются MCP-серверу.

• Список баз данных, схем и каталогов: поиск организационных единиц источника данных SQL. Для Athena не указывайте каталог, чтобы получить список каталогов, или передайте каталог, чтобы получить список баз данных.
• Список таблиц: просмотр таблиц в базе данных или схеме с метаданными (количество строк и размеры, если доступны).
• Описание схемы таблицы: получение имён столбцов, типов, допустимости значений NULL, значений по умолчанию и комментариев.
• Запрос SQL: выполнение SQL-запросов с подстановкой макросов для конкретного источника данных ($__timeFilter(col), $__from/$__to, $__interval, ${varname}), автоматическим ограничением количества результатов и поддержкой переменных шаблона.

Для BigQuery настройте плагин grafana-bigquery-datasource в Grafana. Для поиска используются database для проекта и schema для набора данных. Если database не указан, проект по умолчанию берётся из источника данных defaultProject, а затем из конечной точки плагина /defaultProjects (включая обнаружение проекта GCE). Метаданные извлекаются только через API, без заданий запросов и сканирования таблиц. Включаются описания столбцов и вложенные типы; плагин не предоставляет описания и типы таблиц, допустимость NULL для столбцов и значения по умолчанию.

Для запросов BigQuery требуются полные ссылки на таблицы, например `my-project.my_dataset.fct_events` and use the datasource's billing project. Optional location defaults to datasource processingLocation. Use ${name:sqlstring} для экранированных строковых переменных. Ограничение количества строк не ограничивает объём сканируемых данных или стоимость запросов.

Запросы CloudWatch

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

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

Запросы Google Cloud Logging

Примечание: инструменты Google Cloud Logging по умолчанию отключены. Чтобы включить их, добавьте cloudlogging к флагу --enabled-tools. Требуется версия 1.8.0 или новее плагина источника данных Google Cloud Logging (googlecloud-logging-datasource), для работы которого необходима Grafana 11.2 или новее. Более старые версии плагина возвращают данные в другом формате, и query_cloud_logging выдаёт ошибку с просьбой обновить плагин.

• Список проектов Cloud Logging: поиск идентификаторов проектов GCP, из которых источник данных может читать журналы.
• Список сегментов и представлений Cloud Logging: поиск сегментов журналов и представлений журналов для ограничения области запроса.
• Запрос Cloud Logging: выполнение фильтров на языке запросов Cloud Logging (например, resource.type="k8s_container" AND severity>=ERROR) с указанием диапазона времени и ограничения количества результатов; записи возвращаются от новых к старым и содержат уровень важности, тело, метки и идентификатор трассировки. Аутентификация GCP настраивается в источнике данных.

Запросы Graphite

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

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

Запросы Elasticsearch/OpenSearch

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

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

Запросы Quickwit

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

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

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

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

• Список и поиск диалогов: Просматривайте недавние диалоги LLM или ищите их с помощью выражения фильтра (модель, провайдер, агент, статус, тип ошибки, результаты оценки и многое другое) за указанный период. Результаты поиска включают количество ошибок, сводки оценок, сводки результатов оценки и идентификаторы трассировок.
• Получение сведений о диалоге: Получите один диалог со всеми его генерациями, включая запросы и ответы.
• Получение сведений о генерации и оценках: Получите одну генерацию по ID и её оценки (оценщик, ключ оценки, значение, пройдена ли проверка, пояснение).
• Чтение каталога агентов: Просматривайте агентов, отправляющих телеметрию, получайте полную информацию об одной версии агента (полный системный запрос, все инструменты с их схемами JSON и модели, на которых он запускался), просматривайте историю версий агента и сравнивайте агрегированные оценки по версиям. Эффективные версии — это хеши sha256:, на которые изменения инструментов не влияют; для агента, который не сообщает собственную версию, хешируются системный запрос, поэтому его изменение создаёт новую версию. В строках каталога и версий содержится token_estimate; его стоит проверить перед получением полного запроса.
• Просмотр оценщиков и шаблонов: Читайте сведения об оценщиках, от которых получена оценка, шаблонах, на основе которых они созданы, а также о провайдерах и моделях-судьях, доступных оценщикам LLM-судьям. Если инструменты записи включены, можно также создавать, разветвлять, тестировать и удалять оценщики.
• Просмотр правил оценки и защитных механизмов: Читайте асинхронные правила оценки, связывающие оценщики с рабочим трафиком, и защитные механизмы (правила хуков), которые выполняются встроенно и могут выдавать предупреждения или запрещать действия. Если инструменты записи включены, можно также создавать, обновлять, предварительно просматривать и удалять их. Для операций записи, а также операций 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

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

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

Инциденты

• Поиск, создание и обновление инцидентов: Управляйте инцидентами в Grafana Incident: выполняйте поиск, создавайте инциденты, добавляйте действия, читайте и задавайте пользовательские поля.
• Ресурсы инцидентов: Активные инциденты, начавшиеся за последние 30 дней, также доступны как ресурсы MCP по адресу grafana://irm/incidents/{id}, поэтому их можно напрямую прикрепить к диалогу (например, с помощью @ в Claude Code). Отключаются вместе с инструментами для работы с инцидентами.

Оповещения

• Просмотр списка и получение сведений о правилах оповещений: Просматривайте правила оповещений и их статусы (срабатывает/норма/ошибка и т. д.) в 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: Просматривайте доступные разрешения и возможности назначения для типа ресурса.

Пользователь

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

Навигация

• Создание прямых ссылок: Создавайте точные прямые ссылки на ресурсы 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?schemaVersion=1&panes={"a":{"datasource":"prometheus-uid"}}). Версии Grafana ниже 10.2 не распознают panes, поэтому для них используется устаревший формат ?left={...}.
  • Поддержка временного диапазона: Добавляйте в ссылки параметры временного диапазона (from=now-1h&to=now)
  • Пользовательские параметры: Добавляйте дополнительные параметры запроса, например переменные дашборда или интервалы обновления

Аннотации

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

Снимки

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

Рендеринг

• Получение изображения панели или дашборда: Создавайте PNG-изображение панели Grafana или всего дашборда. Изображение возвращается в формате base64 для использования в отчётах, оповещениях или презентациях. По умолчанию размер панели составляет 1000×750 CSS-пикселей, а всего дашборда — 1200×900 при масштабе 1. Для Explore по умолчанию используется размер 1000×1000 при масштабе 1. Размеры ограничены параметрами области просмотра средства рендеринга изображений. Можно настроить размеры, временной диапазон, тему, масштаб и переменные дашборда. Также поддерживается рендеринг ещё не применённых дашбордов из ветки репозитория подготовки (например, предварительный просмотр 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. Она менее детализирована (а значит, менее ограничительна), чем разрешения, назначенные вручную, поэтому используйте её, только если удобство важнее строгого соблюдения принципа минимальных привилегий.

Примечание: Для инструментов OnCall и других инструментов на основе плагинов используются действия плагинов, например grafana-irm-app.schedules:read. Базовая роль Viewer включает действия чтения, а Editor — действия записи. Для инструментов инцидентов требуется только plugins.app:access; IRM авторизует действия с инцидентами на основе базовой роли.

Действия в формате group/resource:verb, например dashboard.grafana.app/dashboards:get, применяются только к токенам доступа от имени пользователя. Сервисному аккаунту нужны только остальные перечисленные действия.

Дополнительные сведения о 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:read	teams:* или teams:id:1
list_users_by_org	Администратор*	Список пользователей в организации с поиском и постраничной разбивкой	org.users:read	global.users:* или global.users:id:123
list_all_roles	Администратор*	Список всех ролей Grafana	roles:read	roles:*
get_role_details	Администратор*	Получить сведения о роли Grafana	roles:read	roles:uid:editor
get_role_assignments	Администратор*	Список назначений для роли	roles:read, teams.roles:read, users.roles:read	roles:uid:editor
list_user_roles	Администратор*	Список ролей пользователей	users.roles:read	global.users:id:123
list_team_roles	Администратор*	Список ролей команд	teams.roles:read	teams:id:7
get_resource_permissions	Администратор*	Список разрешений для ресурса	dashboards.permissions:read, datasources.permissions:read, folders.permissions:read, serviceaccounts.permissions:read, teams.permissions:read, users.permissions:read	dashboards:uid:abcd1234
get_resource_description	Администратор*	Описание типа ресурса Grafana	dashboards.permissions:read, datasources.permissions:read, folders.permissions:read, serviceaccounts.permissions:read, teams.permissions:read, users.permissions:read	dashboards:*
user_info	Пользователь	Текущая идентификация, возможности и доступные организации	Нет	—
search_dashboards	Поиск	Поиск панелей мониторинга по запросу, UID папки, пути к папке, тегу или признаку избранного	dashboards:read, folders:read	dashboards:* или dashboards:uid:abc123
search_folders	Поиск	Поиск папок по названию	folders:read	folders:* или folders:uid:xyz789
get_dashboard_by_uid	Панель мониторинга	Получить панель мониторинга по UID, при необходимости — сохранённую версию	dashboard.grafana.app/dashboards:get, dashboards:read, dashboards:write	dashboards:uid:abc123
list_dashboard_versions	Панель мониторинга	Список сохранённых версий панели мониторинга (версия, автор, время, сообщение)	dashboards:read, dashboards:write	dashboards:uid:abc123
update_dashboard	Панель мониторинга	Обновить или создать панель мониторинга	dashboard.grafana.app/dashboards:create, dashboard.grafana.app/dashboards:get, dashboard.grafana.app/dashboards:update, dashboards:create, dashboards:read, dashboards:write, folders:read	dashboards:*, folders:* или folders:uid:xyz789
get_dashboard_panel_queries	Панель мониторинга	Получить название панели, запросы, UID и тип источника данных из панели мониторинга	dashboard.grafana.app/dashboards:get, dashboards:read	dashboards:uid:abc123
run_panel_query	RunPanelQuery*	Выполнить один или несколько запросов панели мониторинга	dashboard.grafana.app/dashboards:get, dashboards:read, datasources:query, datasources:read	dashboards:uid:*, datasources:uid:*
get_dashboard_property	Панель мониторинга	Извлечь определённые части панели мониторинга с помощью выражений JSONPath	dashboard.grafana.app/dashboards:get, dashboards:read	dashboards:uid:abc123
get_dashboard_summary	Панель мониторинга	Получить краткую сводку панели мониторинга без полного JSON	dashboard.grafana.app/dashboards:get, dashboards:read	dashboards:uid:abc123
create_folder	Dashboard	Создать папку	folders:create, folders:read, folders:write	folders:*
list_datasources	Datasources	Список источников данных	datasources:read	datasources:*
get_datasource	Datasources	Получить источник данных по UID или имени	datasources:read	datasources:uid:prometheus-uid
check_datasources_health	Datasources	Проверить состояние одного или нескольких источников данных	datasources:query, datasources:read	datasources:uid:*
create_datasource	Datasources	Создать источник данных	datasources:create, datasources:read	datasources:*
update_datasource	Datasources	Обновить источник данных	datasources:read, datasources:write	datasources:* или datasources:uid:abc123
get_query_examples	Examples*	Получить примеры запросов для типа источника данных	None	datasources:*
query_prometheus	Prometheus	Запрашивать метрики с помощью PromQL, не открывая график	datasources:query, datasources:read	datasources:uid:prometheus-uid
render_grafana_app	Rendering	Выполнить включённый инструмент запросов и отобразить результат в интерактивном приложении Grafana	datasources:query, datasources:read	datasources:* или datasources:uid:<uid>
list_prometheus_metric_metadata	Prometheus	Список метаданных метрик	datasources:query, datasources:read	datasources:uid:prometheus-uid
list_prometheus_metric_names	Prometheus	Список доступных имён метрик	datasources:query, datasources:read	datasources:uid:prometheus-uid
list_prometheus_label_names	Prometheus	Список имён меток, соответствующих селектору	datasources:query, datasources:read	datasources:uid:prometheus-uid
list_prometheus_label_values	Prometheus	Список значений для конкретной метки	datasources:query, datasources:read	datasources:uid:prometheus-uid
query_prometheus_histogram	Prometheus	Вычислить значения процентилей гистограммы	datasources:query, datasources:read	datasources:uid:prometheus-uid
list_incidents	Incident	Список инцидентов в Grafana Incident, при необходимости с их значениями пользовательских полей	plugins.app:access	N/A
create_incident	Incident	Создать инцидент в Grafana Incident, при необходимости задав пользовательские поля	plugins.app:access	N/A
add_activity_to_incident	Incident	Добавить запись активности в инцидент в Grafana Incident	plugins.app:access	N/A
update_incident	Incident	Обновить инцидент в Grafana Incident (статус, серьёзность, заголовок или пользовательские поля)	plugins.app:access	N/A
get_incident	Incident	Получить отдельный инцидент по ID, включая пользовательские поля	plugins.app:access	N/A
list_incident_custom_fields	Incident	Список пользовательских полей, настроенных для инцидентов, с их типами и вариантами выбора	plugins.app:access	N/A
query_loki_logs	Loki	Запрашивать и получать журналы с помощью LogQL (запросы журналов или метрик)	datasources:query, datasources:read	datasources:uid:loki-uid
list_loki_label_names	Loki	Перечислить все доступные имена меток в логах	datasources:query, datasources:read	datasources:uid:loki-uid
list_loki_label_values	Loki	Перечислить значения для указанной метки лога	datasources:query, datasources:read	datasources:uid:loki-uid
query_loki_stats	Loki	Получить статистику о потоках логов	datasources:query, datasources:read	datasources:uid:loki-uid
query_loki_patterns	Loki	Запросить обнаруженные шаблоны логов, чтобы выявить распространённые структуры	datasources:query, datasources:read	datasources:uid:loki-uid
analyze_loki_labels	Loki	Проверить стратегию использования меток Loki (в реальном времени или статически) и при необходимости диагностировать производительность запросов	datasources:query, datasources:read	datasources:uid:loki-uid
suggest_loki_alloy_label_config	Config	Создать фрагмент Alloy loki.process, обеспечивающий использование утверждённых меток	None	N/A
query_influxdb	InfluxDB*	Выполнять запросы к InfluxDB с помощью InfluxQL (v1) или Flux (v2)	datasources:query, datasources:read	datasources:uid:influxdb-uid
list_sql_databases	SQL*	Перечислить базы данных, схемы или каталоги источника данных SQL	datasources:query, datasources:read	datasources:uid:*
list_sql_tables	SQL*	Перечислить таблицы в источнике данных SQL	datasources:query, datasources:read	datasources:uid:*
describe_sql_table	SQL*	Получить схему столбцов таблицы	datasources:query, datasources:read	datasources:uid:*
query_sql	SQL*	Выполнять запросы SQL с подстановкой макросов	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_namespaces	CloudWatch*	Перечислить доступные пространства имён AWS CloudWatch	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_metrics	CloudWatch*	Перечислить метрики в пространстве имён	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_dimensions	CloudWatch*	Перечислить измерения для метрики	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_dimension_values	CloudWatch*	Перечислить значения для ключа измерения	datasources:query, datasources:read	datasources:uid:*
query_cloudwatch	CloudWatch*	Выполнять запросы к метрикам CloudWatch	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_log_groups	CloudWatch*	Перечислить группы логов CloudWatch	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_log_group_fields	CloudWatch*	Перечислить поля, обнаруженные в группе логов	datasources:query, datasources:read	datasources:uid:*
query_cloudwatch_logs	CloudWatch*	Выполнять запросы CloudWatch Logs Insights	datasources:query, datasources:read	datasources:uid:*
list_cloud_logging_projects	Cloud Logging*	Перечислить проекты GCP, доступные для чтения источнику данных Google Cloud Logging	datasources:query, datasources:read	datasources:uid:*
list_cloud_logging_buckets	Cloud Logging*	Перечислить корзины логов в проекте GCP	datasources:query, datasources:read	datasources:uid:*
list_cloud_logging_views	Cloud Logging*	Перечислить представления журналов в корзине журналов	datasources:query, datasources:read	datasources:uid:*
query_cloud_logging	Cloud Logging*	Запрашивать журналы с помощью языка запросов Cloud Logging	datasources:query, datasources:read	datasources:uid:*
query_elasticsearch	Elasticsearch/OpenSearch*	Запрашивать Elasticsearch или OpenSearch с помощью синтаксиса Lucene или Query DSL	datasources:query, datasources:read	datasources:uid:datasource-uid
query_quickwit	Quickwit*	Запрашивать Quickwit с помощью синтаксиса Lucene или Query DSL	datasources:query, datasources:read	datasources:uid:quickwit-uid
alerting_rules_read	Alerting	Перечислять и просматривать правила оповещений (список, получение, версии)	alert.rules.external:read, alert.rules:read, datasources:read, folders:read	folders:* или folders:uid:alerts-folder
alerting_rules_write	Alerting	Создавать, обновлять и удалять правила под управлением Grafana или явно создавать правила под управлением источника данных	alert.provisioning.provenance:write, alert.rules.external:read, alert.rules.external:write, alert.rules:create, alert.rules:delete, alert.rules:read, alert.rules:write, datasources:read, folders:read	folders:*, или datasources:uid:<uid> для внешнего создания
alerting_manage_routing	Alerting	Управлять политиками уведомлений, контактными точками и временными интервалами	alert.notifications.external:read, alert.notifications.receivers:read, alert.notifications.routes:read, alert.notifications.time-intervals:read, alert.notifications:read, datasources:query, datasources:read, notifications.alerting.grafana.app/routingtrees:get	Глобальная область
alerting_routing_write	Alerting	По умолчанию создавать контактные точки под управлением Grafana или явно создавать внешние приемники Alertmanager	alert.notifications.external:read, alert.notifications.external:write, alert.notifications.receivers:create, alert.provisioning.provenance:write, datasources:read	Глобальная область или datasources:uid:<uid> для внешнего создания
alerting_silences_read	Alerting	Перечислять и просматривать заглушения оповещений (список, получение)	alert.instances:read, alert.silences:read	Глобальная область
alerting_silences_write	Alerting	Создавать, обновлять и завершать срок действия заглушений оповещений	alert.instances:create, alert.instances:read, alert.instances:write, alert.silences:create, alert.silences:read, alert.silences:write	Глобальная область
list_oncall_schedules	OnCall	Перечислять расписания из Grafana OnCall	grafana-irm-app.schedules:read, plugins.app:access	Области действия, специфичные для плагина
get_oncall_shift	OnCall	Получать сведения о конкретной смене OnCall	grafana-irm-app.schedules:read, plugins.app:access	Области действия, специфичные для плагина
get_current_oncall_users	OnCall	Получать список пользователей, находящихся на дежурстве по определённому расписанию	grafana-irm-app.schedules:read, grafana-irm-app.user-settings:read, plugins.app:access	Области действия, специфичные для плагина
list_oncall_teams	OnCall	Перечислять команды из Grafana OnCall	grafana-irm-app.user-settings:read, plugins.app:access	Области действия, специфичные для плагина
list_oncall_users	OnCall	Перечислять пользователей из Grafana OnCall	grafana-irm-app.user-settings:read, plugins.app:access	Области действия, специфичные для плагина
list_alert_groups	OnCall	Перечислять группы оповещений из Grafana OnCall с параметрами фильтрации	grafana-irm-app.alert-groups:read, plugins.app:access	Области действия, специфичные для плагина
get_alert_group	OnCall	Получать конкретную группу оповещений из Grafana OnCall по её идентификатору	grafana-irm-app.alert-groups:read, plugins.app:access	Области действия, специфичные для плагина
update_alert_group	OnCall	Подтверждать, снимать подтверждение, разрешать или отменять разрешение группы оповещений	grafana-irm-app.alert-groups:read, grafana-irm-app.alert-groups:write, plugins.app:access	Области действия, специфичные для плагина
list_pyroscope_label_names	Pyroscope	Перечислять имена меток, соответствующие селектору	datasources:query, datasources:read	datasources:uid:pyroscope-uid
list_pyroscope_label_values	Pyroscope	Перечислять значения меток, соответствующие селектору для имени метки	datasources:query, datasources:read	datasources:uid:pyroscope-uid
list_pyroscope_profile_types	Pyroscope	Перечислять доступные типы профилей	datasources:query, datasources:read	datasources:uid:pyroscope-uid
query_pyroscope	Pyroscope	Запрашивать профили, метрики или и то и другое из Pyroscope	datasources:query, datasources:read	datasources:uid:pyroscope-uid
agento11y_manage_conversations	Наблюдаемость агентов*	Перечислять, искать и получать беседы LLM из Grafana Agent Observability	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access	Н/Д
agento11y_manage_generations	Наблюдаемость агентов*	Получать сведения о генерациях LLM и оценки результатов из Grafana Agent Observability	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access	Н/Д
agento11y_manage_agents	Наблюдаемость агентов*	Читать каталог агентов: перечислять агентов, получать полную информацию об одной версии агента, просматривать историю версий и сводные оценки по версиям	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access	Н/Д
agento11y_manage_evaluators	Наблюдаемость агентов*	Управлять оценщиками, шаблонами оценщиков и каталогом судей (перечислять, получать, добавлять или обновлять, создавать ответвления, тестировать, удалять)	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; при включенной записи также grafana-agento11y-app.eval:write	Н/Д
agento11y_manage_eval_rules	Наблюдаемость агентов*	Управлять правилами оценки и ограничителями (перечислять, получать, создавать, обновлять, предварительно просматривать, удалять)	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; при включенной записи также grafana-agento11y-app.eval:write	Н/Д
agento11y_manage_eval_collections	Наблюдаемость агентов*	Управлять сохраненными беседами и коллекциями, в которые они объединены (перечислять, получать, сохранять, создавать, обновлять, удалять, добавлять и удалять участников)	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; при включенной записи также grafana-agento11y-app.eval:write	Н/Д
agento11y_manage_experiments	Наблюдаемость агентов*	Читать офлайн-эксперименты, их испытания, оценки, метаданные артефактов и фасеты фильтров; обновлять эксперимент и отменять его	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; при включенной записи также grafana-agento11y-app.eval:write	Н/Д
agento11y_manage_test_suites	Наблюдаемость агентов*	Управлять наборами тестов, на которых выполняются офлайн-эксперименты, их версиями и тестовыми случаями (перечислять, получать, создавать, обновлять, создавать черновики, публиковать, добавлять или обновлять, удалять)	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; при включенной записи также grafana-agento11y-app.eval:write	Н/Д
ask_assistant	Ассистент*	Отправить запрос в Grafana Assistant и вернуть полный текст ответа (многоходовый диалог через contextId)	grafana-assistant-app.chats:access, plugins.app:access	Области действия, специфичные для плагина
generate_deeplink	Навигация	Создавать точные URL для прямых ссылок на ресурсы Grafana	Нет	Н/Д
get_annotations	Аннотации	Получать аннотации с фильтрами	annotations:read	annotations:* или annotations:id:123
create_annotation	Аннотации	Создать аннотацию (в стандартном формате или формате Graphite)	annotations:create	annotations:*
update_annotation	Аннотации	Обновить отдельные поля аннотации (частичное обновление)	annotations:read, annotations:write	annotations:*
delete_annotation	Аннотации	Удалить аннотацию по ID	annotations:delete	annotations:*
get_annotation_tags	Аннотации	Перечислить теги аннотаций с необязательной фильтрацией	annotations:read	annotations:*
list_snapshots	Снимок	Перечислить снимки дашбордов с необязательными фильтрами запроса и ограничения	snapshots:read	Н/Д
get_snapshot	Снимок	Получить метаданные снимка и данные дашборда по ключу снимка	Нет	Н/Д
create_snapshot	Снимок	Создать снимок дашборда из полного набора данных дашборда	dashboards:read, snapshots:create	dashboards:uid:abc123
delete_snapshot	Снимок	Удалить снимок дашборда по ключу снимка	dashboards:write, snapshots:delete	dashboards:uid:abc123
get_panel_image	Рендеринг	Преобразовать сохраненный дашборд или панель, предварительный просмотр конфигурации или специальное представление Explore в изображение PNG	dashboards:read, datasources:explore, datasources:query, datasources:read, provisioning.repositories:read	dashboards:uid:abc123
list_provisioning_repositories	Подготовка	Перечислить репозитории подготовки (например, источники git-sync), указав URL источника, ветку, состояние синхронизации и работоспособность	provisioning.grafana.app/repositories:list, provisioning.repositories:read	Н/Д
validate_provisioning_file	Provisioning	Выполнить пробное применение файла из репозитория provisioning и сообщить об ошибках проверки admission	dashboard.grafana.app/dashboards:get, dashboards:read, folder.grafana.app/folders:get, folders:read, provisioning.grafana.app/repositories:get, provisioning.repositories:read	N/A
search_docs	Docs	Искать в документации Grafana или перечислить группы продуктов (не указывайте запрос, чтобы перечислить продукты)	None	N/A
get_doc	Docs	Получить страницу документации; задайте outline_only для заголовков или section для ограниченного извлечения	None	N/A
search_tempo_traces	Tempo	Искать трассировки с помощью TraceQL	datasources:query, datasources:read	datasources:uid:tempo-uid
query_tempo_metrics	Tempo	Вычислять метрики по трассировкам с помощью TraceQL	datasources:query, datasources:read	datasources:uid:tempo-uid
get_tempo_trace	Tempo	Получить трассировку по ID	datasources:query, datasources:read	datasources:uid:tempo-uid
diff_tempo_traces	Tempo	Сравнить две трассировки	datasources:query, datasources:read	datasources:uid:tempo-uid
list_tempo_attribute_names	Tempo	Перечислить имена атрибутов span и ресурса	datasources:query, datasources:read	datasources:uid:tempo-uid
list_tempo_attribute_values	Tempo	Перечислить значения атрибута трассировки	datasources:query, datasources:read	datasources:uid:tempo-uid
get_tempo_traceql_docs	Tempo	Получить документацию TraceQL	None	N/A
query_graphite	Graphite*	Запрашивать метрики Graphite	datasources:query, datasources:read	datasources:uid:graphite-uid
query_graphite_density	Graphite*	Запрашивать плотность метрик Graphite	datasources:query, datasources:read	datasources:uid:graphite-uid
list_graphite_metrics	Graphite*	Перечислить метрики Graphite	datasources:query, datasources:read	datasources:uid:graphite-uid
list_graphite_tags	Graphite*	Перечислить теги Graphite	datasources:query, datasources:read	datasources:uid:graphite-uid
get_plugin	Plugins	Получить установленный плагин	plugins.app:access	N/A
search_plugin_information	Plugins	Искать в каталоге плагинов grafana.com	None	N/A
install_plugin	Plugins	Установить плагин	plugins:install	N/A
grafana_api_request	API	Вызвать конечную точку HTTP API Grafana	None	Зависит от конечной точки
* По умолчанию отключено. Добавьте категорию в --enabled-tools, чтобы включить.

Инструмент render_grafana_app отображает метрики и трассировки в совместимых MCP-хостах, если включены категории визуализации и соответствующих запросов. Инструменты исходных запросов возвращают текст и структурированные данные для анализа. Инструкции по настройке и встраиванию библиотеки см. в разделе MCP Apps.

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

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

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

• -t, --transport: тип транспорта (stdio, sse или streamable-http) — по умолчанию: stdio
• --address: хост и порт для сервера SSE/streamable-http — по умолчанию: localhost:8000
• --base-path: базовый путь для сервера SSE/streamable-http. /healthz и /metrics всегда доступны в корне сервера, а не по этому префиксу: это внутренние конечные точки только для проверок и сборщиков данных, и их размещение вне префикса приложения упрощает публикацию API через обратный прокси без одновременной публикации этих конечных точек
• --endpoint-path: путь конечной точки сервера streamable-http, добавляемый к --base-path — по умолчанию: /mcp
• --sse-keepalive: интервал между ping-запросами, отправляемыми каждому клиенту SSE, чтобы обратные прокси и балансировщики нагрузки не закрывали простаивающий поток событий (что завершает сеанс). Задайте значение меньше тайм-аута простоя прокси, например 30s при использовании стандартного тайм-аута 60 с proxy-read-timeout в ingress-nginx. Клиент отключается, если на 3 ping-запроса подряд не поступает ответ в течение половины интервала на каждый запрос. Принимает строки длительности Go, минимум 1s — по умолчанию: 0 (отключено). Применяется только к --transport sse
• --server-name: имя сервера, используемое при рукопожатии MCP и в OTel service.name — по умолчанию: mcp-grafana. Переопределяет переменную окружения GRAFANA_MCP_SERVER_NAME
• --instructions-append: текст, добавляемый к инструкциям сервера, возвращаемым MCP-клиентам при инициализации, чтобы каждый подключающийся агент видел его

Когда --address использует порт 0, операционная система выделяет свободный порт, а сервер атомарно записывает адрес привязки в mcp-grafana-address в рабочем каталоге. Файл создаётся с режимом 0600.

[!NOTE] При использовании SSE заголовки отдельных запросов не передаются вызовам инструментов: X-Grafana-Service-Account-Token / X-Grafana-API-Key, X-Grafana-Org-Id и заголовки, перечисленные в GRAFANA_FORWARD_HEADERS, не действуют; вызовы инструментов используют учётные данные сервера из окружения, а переопределения X-Grafana-URL не работают. Используйте streamable-http, если каждому вызывающему клиенту нужны собственные URL Grafana, учётные данные или организация.

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

Проверка Host/Origin выполняется для всех маршрутов MCP-слушателя — /sse, /mcp и /healthz / /metrics, если они используют тот же слушатель, — поэтому браузер с атакой DNS rebinding не сможет обратиться ни к одному из них. На транспорт stdio это не влияет. --healthz-address и --metrics-address запускают отдельный слушатель, к которому эта проверка не применяется.

• --allowed-hosts: список разрешённых значений заголовка Host, разделённых запятыми. По умолчанию используются варианты --address для loopback (например, localhost:8000,127.0.0.1:8000,[::1]:8000). Если значение после разбора оказывается пустым (не задано, ,, , и т. д.), также используются значения по умолчанию, чтобы опечатка не отключила проверку незаметно. Запросы с заголовком Host, значение которого отсутствует в списке, отклоняются с кодом 403. Передайте *, чтобы отключить проверку Host; это безопасно только в том случае, если доверенный обратный прокси проверяет Host. Для проверок K8s httpGet и внешнего сбора данных /metrics потребуется либо явно указать имя хоста в этом списке, либо использовать *, проверку tcpSocket или отдельный порт (--healthz-address / --metrics-address).
• --allowed-origins: список разрешённых значений заголовка Origin, разделённых запятыми. По умолчанию пуст. Любой запрос с заголовком Origin отклоняется (браузеры всегда отправляют его для междоменных запросов, и ни один браузер не должен обращаться к этому серверу напрямую). Укажите явный список, чтобы разрешить клиентов на основе браузера, или *, чтобы отключить проверку.
• --allow-grafana-url-override: включить выбор X-Grafana-URL. Если значение не задано, используется GRAFANA_ALLOW_URL_OVERRIDE; по умолчанию отключено. Без списка разрешённых адресов вызывающие клиенты могут выбрать любой доступный серверу URL HTTP(S).
• --allowed-grafana-urls: необязательный список точных базовых URL Grafana, разрешённых для переопределения URL, разделённых запятыми. Если значение не задано, используется GRAFANA_ALLOWED_URLS. Требует --allow-grafana-url-override; явный пустой флаг отключает унаследованный список.

Аутентификация вызывающих клиентов (только 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 это не влияет); в будущем крупном выпуске это станет ошибкой запуска. Если аутентификация вызывающих клиентов включена для адреса, отличного от loopback, используйте TLS (или завершение TLS). При включённой аутентификации проверенный заголовок Authorization удаляется перед передачей запросов в Grafana; сочетание --server-auth-token с GRAFANA_FORWARD_HEADERS=Authorization приводит к ошибке запуска.

Переопределение URL Grafana (только streamable-http):

[!WARNING] Переопределение URL позволяет вызывающим MCP-клиентам выбирать адреса назначения для исходящих запросов HTTP(S). Список разрешённых адресов ограничивает URL, но не аутентифицирует вызывающих клиентов и не привязывает токены к адресам назначения.

Размещайте сервер за аутентифицирующим прокси, который проверяет права доступа к каждому адресу назначения, заменяет переданные клиентом заголовки URL и токена и предоставляет соответствующий токен. Ограничьте исходящий сетевой доступ сервера разрешёнными адресами.

Без списка разрешённых адресов поддельный токен запроса может направить запросы к любой доступной службе HTTP(S), включая внутренние службы и службы метаданных.

Задайте GRAFANA_ALLOW_URL_OVERRIDE=true (или --allow-grafana-url-override), чтобы включить выбор для большого парка серверов. Чтобы ограничить адреса назначения, также задайте GRAFANA_ALLOWED_URLS=https://one.example.com,https://two.example.com/grafana (или --allowed-grafana-urls).

Передавайте эти заголовки с каждым MCP-запросом, в котором выбирается адрес назначения:

X-Grafana-URL: https://one.example.com
X-Grafana-Service-Account-Token: <token for one.example.com>

Если настроен --server-auth-token, также передавайте Authorization: Bearer <MCP caller token>. Этот параметр обеспечивает аутентификацию на MCP-сервере и не связан с X-Grafana-Service-Account-Token, который используется для выбранного экземпляра Grafana. Ваш прокси может передавать разные токены Grafana для разных экземпляров; сервер не использует один настроенный токен для всех экземпляров. Также поддерживается устаревший заголовок X-Grafana-API-Key. Запрос с заголовком URL без токена Grafana отклоняется. Используйте TLS для входящих запросов, поскольку они содержат токены.

Список разрешённых адресов сопоставляется с точными базовыми URL, включая схему, порт и путь; подстановочные знаки не поддерживаются. Аутентификация Grafana не защищает от SSRF.

Для выбранного URL сервер не использует GRAFANA_SERVICE_ACCOUNT_TOKEN, GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE, GRAFANA_API_KEY, базовую аутентификацию из окружения, GRAFANA_EXTRA_HEADERS или клиентские сертификаты. Проверка TLS остаётся включённой, даже если задан --tls-skip-verify; настроенный файл CA по-прежнему применяется. Явно переданные из этого запроса заголовки продолжают действовать. Перенаправления и другие запросы к API Grafana за пределами выбранного базового URL блокируются. Для запросов без X-Grafana-URL сохраняется обычное поведение GRAFANA_URL и учётных данных из окружения. Этот параметр применяется только к streamable HTTP. Он не работает через SSE, поскольку этот транспорт не передаёт заголовки отдельных запросов вызовам инструментов; выбранный URL используется без токена вызывающего клиента, поэтому вызовы завершаются ошибкой.

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

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

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

• --grafana-timeout: ограничение времени для запросов клиента Grafana. Принимает строки длительности Go (например, 10s, 500ms) — по умолчанию: 30s
• --allow-cross-origin-redirects: разрешить исходящим клиентам Grafana следовать перенаправлениям на другой протокол, хост или порт. По умолчанию отключено; резервное значение берётся из переменной окружения GRAFANA_ALLOW_CROSS_ORIGIN_REDIRECTS. Включение может привести к передаче учётных данных Grafana целевому адресу перенаправления. URL Grafana, выбранные в запросе, остаются привязанными к выбранному адресу.
• --include-args-in-spans: включать аргументы вызовов инструментов в спаны OpenTelemetry. Включайте только в непроизводственных средах или если известно, что аргументы не содержат персональных данных — по умолчанию: false

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

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

Анонимная статистика использования:

• --usage-stats: отправка анонимной статистики использования: enabled, disabled или log (вывести в stderr отчёт, который был бы отправлен, и ничего не отправлять). Переопределяет переменную окружения GRAFANA_USAGE_STATS, которая, в свою очередь, переопределяет DO_NOT_TRACK; любое нераспознанное значение отключает отправку статистики. См. раздел Анонимная статистика использования. Конфигурация инструментов:

• --enabled-tools: Список включённых категорий, разделённых запятыми — по умолчанию: все категории, кроме admin, agento11y, assistant, athena, clickhouse, cloudlogging, cloudwatch, dsquery, elasticsearch, examples, graphite, quickwit, runpanelquery и snowflake. Чтобы включить отключённые категории, добавьте их в список (например, "search,datasource,...,snowflake")

• --max-loki-log-limit: Максимальное количество возвращаемых строк журнала за один вызов query_loki_logs — по умолчанию: 100. Примечание: задайте значение как минимум на 1 меньше серверного ограничения Loki max_entries_limit_per_query, чтобы можно было обнаружить усечение (инструмент внутренне запрашивает limit+1, чтобы определить, есть ли дополнительные данные).

• --loki-guardrail-mode: Ограничитель стоимости запросов Loki для query_loki_logs — по умолчанию: off. Loki не применяет max_query_bytes_read к запросам журналов без фильтра строк, поэтому широкий селектор за большой период может просканировать терабайты данных; ограничитель требует селектор потока с узким охватом, ограничивает эффективный временной диапазон (включая длительности векторов диапазона, например [30d]) и перед выполнением запроса проверяет оценку объёма данных по индексу/статистике Loki. shadow регистрирует запросы, которые были бы заблокированы, но позволяет им выполняться (при этом всё равно выполняется обращение к индексу/статистике); enforce отклоняет их и предоставляет рекомендации по переписыванию, которые LLM может применить. В VictoriaLogs ограничитель применяется только к запросам формы селектора ({...}): если селектор не разбирается (обычная форма LogsQL без фигурных скобок), запрос проходит без ограничений, а проверка бюджета байтов не выполняется (нет дешёвой оценки по индексу). Резервное значение из окружения: GRAFANA_LOKI_GUARDRAIL_MODE.

• --loki-guardrail-max-bytes: Максимальный объём данных, который может просканировать один вызов query_loki_logs, согласно оценке API индекса/статистики Loki — по умолчанию: 107374182400 (100 GiB). Значение 0 отключает проверку бюджета байтов. Резервное значение из окружения: GRAFANA_LOKI_GUARDRAIL_MAX_BYTES.

• --loki-guardrail-max-range: Максимальный эффективный временной диапазон для одного вызова query_loki_logs, включая длительности векторов диапазона — по умолчанию: 24h. Принимает строки длительности Go. Значение 0 отключает проверку диапазона. Резервное значение из окружения: GRAFANA_LOKI_GUARDRAIL_MAX_RANGE.

• --prometheus-guardrail-mode: Ограничитель запросов Prometheus для query_prometheus, query_prometheus_histogram и запросов Prometheus в run_panel_query — по умолчанию: off. Ограничитель ограничивает эффективный временной диапазон запроса и количество точек на ряд, которые он запрашивает, прежде чем запрос достигнет источника данных. Независимая политика селекторов, включаемая по желанию, может требовать непустое положительное ограничение по метке помимо имени метрики в каждом векторном селекторе; примеры и ограничения см. в разделе политика селекторов. shadow регистрирует запросы, которые были бы заблокированы, но позволяет им выполняться; enforce отклоняет их и предоставляет рекомендации по переписыванию, которые LLM может применить (run_panel_query указывает это в записи errors результата для соответствующей панели). Резервное значение из окружения: GRAFANA_PROMETHEUS_GUARDRAIL_MODE.

• --prometheus-guardrail-require-selective-labels: Требовать, чтобы каждый векторный селектор содержал непустое положительное ограничение по метке помимо имени метрики. По умолчанию: false; независимо от бюджетов диапазона и точек, в том числе когда оба равны 0. Применяется только если режим ограничителя не равен off. Резервное значение из окружения: GRAFANA_PROMETHEUS_GUARDRAIL_REQUIRE_SELECTIVE_LABELS. Явные значения CLI, включая false, имеют приоритет над окружением.

• --prometheus-guardrail-max-range: Максимальный эффективный временной диапазон для одного запроса PromQL — по умолчанию: 192h. Эффективный диапазон — это собственный временной диапазон запроса (ноль для мгновенных запросов) плюс самое длинное окно вектора диапазона или подзапроса в выражении; диапазоны вложенных подзапросов суммируются, поэтому max_over_time(rate(x[5m])[30d:1m]) означает 30d5m. Принимает строки длительности Go, поэтому указывайте 192h, а не 8d. Значение 0 отключает проверку диапазона. Резервное значение из окружения: GRAFANA_PROMETHEUS_GUARDRAIL_MAX_RANGE.

• --prometheus-guardrail-max-points: Максимальное количество точек на ряд, которое может запрашивать запрос диапазона, floor(range / step) + 1 — по умолчанию: 11000, собственное ограничение Prometheus на ряд. В рекомендациях указывается наименьшее значение stepSeconds, которого достаточно. Значение 0 отключает проверку количества точек. Резервное значение из окружения: GRAFANA_PROMETHEUS_GUARDRAIL_MAX_POINTS.

• --prometheus-guardrail-max-metric-cardinality: Политика области действия TSDB, включаемая по желанию. По умолчанию: 0 (отключена). Для точного имени метрики, число рядов которой превышает указанный порог, требуется непустое точное совпадение по настроенной метке области действия. Активна только если режим не равен off. Резервное значение из окружения: GRAFANA_PROMETHEUS_GUARDRAIL_MAX_METRIC_CARDINALITY.

• --prometheus-guardrail-cardinality-cache-ttl: Срок хранения кэшированных снимков TSDB. По умолчанию: 10m; 0 также использует 10m. Резервное значение из окружения: GRAFANA_PROMETHEUS_GUARDRAIL_CARDINALITY_CACHE_TTL.

• --prometheus-guardrail-cardinality-scope-labels: Список меток, разделённых запятыми; их непустые точные совпадения удовлетворяют политике кардинальности. По умолчанию: job,instance,namespace,pod,service,cluster; пустое значение использует эти значения по умолчанию. __name__ не допускается. Резервное значение из окружения: GRAFANA_PROMETHEUS_GUARDRAIL_CARDINALITY_SCOPE_LABELS. Явные настройки CLI переопределяют соответствующие переменные окружения.

  Ограничения ограничителя Prometheus: проверка количества точек учитывает запрошенное разрешение, а не число рядов, образцов или вычислений подзапросов; Grafana может выровнять диапазон или увеличить шаг. Модификаторы offset и @ игнорируются. Макросы Grafana, такие как $__rate_interval и $__range, подставляются до измерения выражения с использованием значений Grafana ($__rate_interval равен четырём шагам). Если ограничитель всё ещё не может разобрать выражение (например, из-за переменных панели мониторинга, таких как $window, или синтаксиса, поддерживаемого только другим диалектом), проверяются только собственный временной диапазон и шаг запроса, после чего запрос выполняется. У run_panel_query нет параметра шага, поэтому для длинных диапазонов он увеличивает шаг в 1 минуту, чтобы уложиться в 11000 точек, как это делает Grafana, либо в меньшее значение --prometheus-guardrail-max-points в режиме enforce.

• --prometheus-enforced-matchers: Сопоставители меток PromQL, добавляемые через AND к каждому запросу к нативному Prometheus, чтобы ограничить доступные для чтения ряды (например, environment=~"prod|staging"). Требует --disable-api. См. раздел принудительное применение ограничений запросов Prometheus.

• --loki-enforced-matchers: Сопоставители меток LogQL, добавляемые через AND к каждому запросу к нативному Loki, чтобы ограничить доступные для чтения потоки журналов (например, environment=~"prod|staging"). Требует --disable-api. См. раздел принудительное применение ограничений запросов Loki.

• --loki-label-enumeration-fallback: Поведение инструментов перечисления меток, если отрицательные принудительно заданные сопоставители не позволяют ограничить их область действия: reject (по умолчанию) или unfiltered. См. раздел принудительное применение ограничений запросов Loki.

• --dashboard-schema: Установите значение v2, чтобы update_dashboard отклонял тело классической версии v1 (panels[]), которое создало бы новую панель мониторинга, если Grafana использует схему панели мониторинга v2; ошибка содержит минимальное тело v2 для повторной попытки. Существующие панели мониторинга v1 по-прежнему можно редактировать, а Grafana без v2 не затрагивается. По умолчанию: пусто (без изменений). Резервное значение из окружения: GRAFANA_DASHBOARD_SCHEMA.

• --disable-search: Отключить инструменты поиска

• --disable-datasource: Отключить инструменты источников данных

• --disable-incident: Отключить инструменты инцидентов

• --disable-prometheus: Отключить инструменты Prometheus

• --disable-write: Отключить инструменты записи (операции создания/обновления)

• --disable-query: Отключить инструменты запросов (инструменты, выполняющие запрос к источнику данных); инструменты метаданных и обнаружения остаются доступными

• --enable-query: Оставить зарегистрированными инструменты запросов с необработанным SQL (query_sql, query_influxdb) даже при --disable-write, а также оставить доступным query_datasource, источник render_grafana_app. Для инструментов с необработанным SQL это эквивалентно --enable-write-tools=query_sql,query_influxdb; параметр сохранён как сокращённая запись для этого распространённого случая.

• --enable-write-tools: Список отдельных имён инструментов, разделённых запятыми, которые следует оставить зарегистрированными даже при --disable-write, если поведение записи инструмента достаточно ограничено, чтобы включить его отдельно. Не влияет на инструмент, категория которого отключена целиком. Например, --enable-write-tools=generate_deeplink оставляет сокращение URL (shorten=true) доступным при --disable-write, а --enable-write-tools=alerting_rules_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-admin: Отключить инструменты администрирования

• --disable-pyroscope: Отключить инструменты Pyroscope

• --disable-navigation: Отключить инструменты навигации

• --disable-rendering: Отключить инструменты рендеринга (экспорт изображений панелей/панелей мониторинга)

• --disable-snapshot: Отключить инструменты снимков

• --disable-cloudwatch: Отключить инструменты CloudWatch

• --disable-cloudlogging: Отключить инструменты Google Cloud Logging

• --disable-examples: Отключить инструменты примеров запросов

• --disable-sql: Отключить инструменты SQL-источников данных (ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, MSSQL, BigQuery). Также работают псевдонимы --disable-clickhouse, --disable-snowflake, --disable-athena.

• --disable-runpanelquery: Отключить инструменты выполнения запросов панели

• --disable-graphite: Отключить инструменты Graphite

• --disable-dsquery: Отключить источник query_datasource для render_grafana_app

• --disable-provisioning: Отключить инструменты подготовки ресурсов

• --disable-agento11y: Отключить инструменты Agent Observability

• --disable-assistant: Отключить инструменты Grafana Assistant

• --disable-docs: Отключить инструменты документации

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

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

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

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

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

• update_dashboard

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

• create_folder

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

• create_incident
• add_activity_to_incident
• update_incident

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

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

Каждый инструмент записи оповещений можно оставить включённым отдельно с помощью --enable-write-tools=<name>.

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

• update_alert_group

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

• create_annotation
• update_annotation
• delete_annotation

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

• create_snapshot
• delete_snapshot

Инструменты навигации:

• generate_deeplink (shorten=true игнорируется, возвращается полный URL; передайте --enable-write-tools=generate_deeplink, чтобы оставить сокращение URL включённым)

Инструменты запросов с необработанным SQL:

Они выполняют любой переданный запрос без проверки, поэтому могут выполнять запись, если это разрешают учётные данные источника данных: query_sql выполнит DROP TABLE, а query_influxdb выполнит DELETE. Поэтому в режиме только для чтения они удаляются. Передайте --enable-query, чтобы оставить их включёнными, если известно, что учётные данные источника данных предоставляют доступ только для чтения.

• query_sql
• query_influxdb

Инструменты Agent Observability:

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

Все операции чтения остаются доступными: можно запрашивать панели мониторинга, выполнять запросы PromQL/LogQL, перечислять ресурсы и получать данные. Языки запросов, не позволяющие выполнять запись, — PromQL, LogQL, TraceQL, Elasticsearch DSL, Graphite и CloudWatch — сохраняют свои инструменты запросов в режиме только для чтения; удаляются только перечисленные выше инструменты с необработанным SQL.

Режим без запросов

Флаг --disable-query удаляет все инструменты, выполняющие запросы к источнику данных, но оставляет инструменты для работы с метаданными и обнаружения. Это полезно, если вам нужен ассистент, который может изучать доступные ресурсы — источники данных, дашборды, названия метрик, метки, схемы таблиц — без выполнения потенциально затратных запросов или запросов, раскрывающих данные. Например, когда у сервисной учётной записи есть datasources:read, но нет datasources:query.

Это самый строгий из трёх параметров запросов, и он имеет приоритет над --enable-query:

Флаги	Безопасные инструменты запросов (query_prometheus, query_loki_logs, run_panel_query, …)	Инструменты запросов с необработанным SQL (query_sql, query_influxdb)
(none)	зарегистрированы	зарегистрированы
--disable-write	зарегистрированы	не зарегистрированы
--disable-write --enable-query	зарегистрированы	зарегистрированы
--disable-query	не зарегистрированы	не зарегистрированы
--disable-query --enable-query	не зарегистрированы	не зарегистрированы

Если включён параметр --disable-query, следующие инструменты не регистрируются:

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

• query_prometheus
• query_prometheus_histogram

Инструменты визуализации:

• render_grafana_app

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

• query_loki_logs
• query_loki_patterns

query_loki_stats и analyze_loki_labels остаются зарегистрированными: оба отправляют селектор источнику данных, но считывают индекс и возвращают количество потоков, фрагментов и байтов, а не содержимое журналов.

Инструменты Elasticsearch/OpenSearch и Quickwit:

• query_elasticsearch
• query_quickwit

Инструменты InfluxDB (также удаляются параметром --disable-write, см. выше):

• query_influxdb

Инструменты источников данных SQL (также удаляются параметром --disable-write, см. выше):

• query_sql

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

• query_graphite
• query_graphite_density

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

• query_cloudwatch
• query_cloudwatch_logs

Инструменты Google Cloud Logging:

• query_cloud_logging

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

• query_pyroscope

Инструменты выполнения запросов к панелям:

• run_panel_query

Категории elasticsearch, quickwit, influxdb и runpanelquery не содержат других инструментов, поэтому при отключённых запросах в них не регистрируется ни одного инструмента. Одноимённые инструменты во всех остальных категориях — list_prometheus_metric_names, list_loki_label_values, describe_sql_table, list_cloudwatch_metrics, list_cloud_logging_projects и так далее — остаются доступными.

Обратите внимание: параметр --disable-query ограничивает инструменты запросов и путь POST к /api/ds/query через grafana_api_request, но не контролирует все способы обращения к источнику данных. В режиме только для чтения grafana_api_request разрешает POST к /api/ds/query только при включённых инструментах запросов (тот же механизм ограничения, что и для инструментов с необработанным SQL: запросы блокируются параметром --disable-write, если его не переопределяет --enable-query). На get_panel_image, который выполняет визуализацию панели на стороне сервера, это не влияет.

Настройка TLS клиента (для подключений к Grafana):

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

Настройка TLS сервера (только для транспорта 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 минуты). В сочетании с кэшем клиентов для каждого запроса, ключом которого служит значение токена, обновлённый токен автоматически создаёт новый клиент — перезапуск пода и простой не требуются:

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 при использовании транспорта streamable HTTP (заголовок имеет приоритет над переменной среды, поэтому можно также задать организацию по умолчанию).

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

Динамический выбор организации (для каждого вызова)

Параметры выше задают организацию для всего подключения. Чтобы одно подключение могло обращаться к разным организациям при каждом вызове инструмента, запустите сервер с флагом --dynamic-multi-org. По умолчанию он отключён.

Если этот параметр включён, каждый инструмент принимает необязательный аргумент orgId, который переопределяет организацию подключения для данного вызова (задавая заголовок X-Grafana-Org-Id и, для API платформы приложений, разрешённое пространство имён Kubernetes). Кроме того, проксируемые инструменты источников данных обнаруживаются во всех организациях, к которым у учётных данных есть доступ. Если в вызове не указан orgId, используется организация подключения по умолчанию.

Это работает только с учётными данными, связанными более чем с одной организацией (например, с учётной записью пользователя или идентификатором, действующим от имени пользователя); токен сервисной учётной записи по-прежнему привязан к одной организации. Используйте инструмент user_info, чтобы узнать допустимые значения orgId.

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

{
  "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-заголовки

С помощью переменной среды GRAFANA_EXTRA_HEADERS можно добавлять произвольные HTTP-заголовки ко всем запросам к API Grafana. Значение должно быть объектом 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\"}"
      }
    }
  }
}

Прокси SOCKS5

С помощью переменной среды GRAFANA_SOCKS5_PROXY можно направлять все запросы этого сервера к Grafana через прокси SOCKS5. Прокси применяется только к трафику этого сервера, направленному в Grafana: он не изменяет глобальные переменные HTTP_PROXY/HTTPS_PROXY, а при задании переопределяет выбор прокси для транспортов Grafana, не затрагивая другие MCP-серверы и сеанс оболочки. Если переменная не задана, поведение не меняется.

URL должен использовать схему socks5:// или socks5h:// (Go обрабатывает их одинаково: разрешение имени хоста выполняет прокси) и может содержать учётные данные, например socks5://user:pass@127.0.0.1:1080.

Пример:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your token>",
        "GRAFANA_SOCKS5_PROXY": "socks5://127.0.0.1:1080"
      }
    }
  }
}

Некорректный URL прокси приводит к ошибке при запуске. Если во время работы не удаётся установить соединение через прокси, сервер прекращает работу, а не отправляет трафик Grafana напрямую.

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

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

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

Пример: пересылка файла 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. Если имя заголовка указано в обоих источниках, для этого запроса используется значение из входящего запроса.

Заголовки контекста трассировки (traceparent, tracestate, baggage) являются исключением: сервер самостоятельно передаёт контекст трассировки, поэтому пересылаемое значение не переопределяет добавленное сервером. См. раздел наблюдаемость.

2. Установить mcp-grafana можно несколькими способами:

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

     uvx mcp-grafana
     

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

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

     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 это не влияет. См. раздел Аутентификация вызывающей стороны.

     2. Режим 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
     

     3. Режим 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
     

     Для режима Streamable HTTP с HTTPS и сертификатами 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/v2/cmd/mcp-grafana@latest
     

   • Развернуть в Kubernetes с помощью Helm: используйте Helm chart из репозитория 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
     

3. Добавьте конфигурацию сервера в файл конфигурации клиента. Например, для 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"
         }
       }
     }
   }
   

Примечание: если в Claude Desktop отображается Error: spawn mcp-grafana ENOENT, необходимо указать полный путь к 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 с потоковым 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
• Клиенты управления инцидентами
• Клиенты оповещений
• Клиенты 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 сервера (только для транспорта с потоковым HTTP)

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

Для транспорта с потоковым HTTP сервер поддерживает следующие параметры настройки TLS:

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

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

Пример HTTPS-сервера с потоковым 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) или потокового 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

# Probe a side listener while MCP stays on loopback (Kubernetes + sidecar)
./mcp-grafana -t streamable-http --address 127.0.0.1:8000 --healthz-address :8080
curl http://127.0.0.1:8080/healthz

# With --base-path /my-base the MCP routes move under the prefix
# (/my-base/sse, /my-base/mcp), but healthz does not:
curl http://localhost:8000/healthz          # 200 ok
curl http://localhost:8000/my-base/healthz  # 404

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

Анонимная статистика использования

Сервер может отправлять Grafana Labs анонимную статистику о своём использовании: какие инструменты вызывались, сколько вызовов завершились ошибкой и как настроен сервер. Один отчёт охватывает один процесс сервера — не одного пользователя и не один разговор — и отправляется каждые 4 часа, а также один раз при завершении работы. Отправка отчётов включена по умолчанию. Чтобы отказаться от неё, задайте --usage-stats=disabled, GRAFANA_USAGE_STATS=disabled или DO_NOT_TRACK=1.

Аргументы инструментов, имена ресурсов, запросы, строки журналов, сообщения об ошибках и учётные данные никогда не отправляются. Флаги записываются только по имени, но не по значению, а экземпляр Grafana описывается только как cloud или self_hosted — URL, имя хоста, идентификатор стека и организации не передаются. Данные не привязаны к пользователю, сеансу или клиенту: в передаваемых данных нет идентификатора сеанса, и невозможно связать вызов инструмента с конкретным клиентом.

# Turn reporting on
mcp-grafana --usage-stats=enabled

# Turn it off (or GRAFANA_USAGE_STATS=disabled)
mcp-grafana --usage-stats=disabled

# Print what would be sent, to stderr, and send nothing
GRAFANA_USAGE_STATS=log mcp-grafana

DO_NOT_TRACK=1 также отключает отправку отчётов в соответствии с общим соглашением DO_NOT_TRACK для разных инструментов. Действует только 1, который может лишь отключить отправку; при этом --usage-stats и GRAFANA_USAGE_STATS имеют приоритет, поэтому хост, задающий эту переменную глобально, всё равно может повторно включить отправку для отдельного сервера.

GRAFANA_USAGE_STATS_ENDPOINT меняет адрес назначения. Это не способ отказаться от отправки.

Полный список полей, сведения о том, что никогда не отправляется, а также описание того, как читать данные и каковы их ограничения, см. в разделе Анонимная статистика использования.

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

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

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

Метрики

При использовании транспорта SSE или потокового 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)
http_server_request_duration_seconds	Гистограмма	Длительность запросов HTTP-сервера (из otelhttp)

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

Когда включён ограничитель затрат Loki (--loki-guardrail-mode), ещё четыре счётчика фиксируют его решения:

Метрика	Тип	Описание
mcp_loki_guardrail_admitted_total	Счётчик	Запросы, прошедшие все включённые проверки (метки: backend)
mcp_loki_guardrail_would_block_total	Счётчик	Запросы, не прошедшие проверку в режиме shadow, но всё равно выполненные (метки: backend, reason)
mcp_loki_guardrail_blocked_total	Счётчик	Запросы, отклонённые в режиме enforce (метки: backend, reason)
mcp_loki_guardrail_fail_open_total	Счётчик	Запросы, которые ограничитель не смог оценить, но пропустил (метки: backend, cause)

reason принимает одно из значений selector, range, bytes; cause принимает одно из значений unparseable, estimate_failed; backend принимает одно из значений loki, victorialogs, unknown. Запрос, не прошедший несколько проверок, учитывается один раз и помечается проверкой, выполненной первой (selector, затем range, затем bytes), поэтому четыре счётчика охватывают всю совокупность запросов, проверяемых ограничителем. О том, как интерпретировать их при переходе shadow → enforce, см. раздел Наблюдаемость.

Когда включён ограничитель Prometheus (--prometheus-guardrail-mode), четыре счётчика аналогичным образом фиксируют его решения:

Метрика	Тип	Описание
mcp_prometheus_guardrail_admitted_total	Счётчик	Запросы, прошедшие все включённые проверки
mcp_prometheus_guardrail_would_block_total	Счётчик	Запросы, не прошедшие проверку в режиме shadow, но всё равно выполненные (метки: reason)
mcp_prometheus_guardrail_blocked_total	Счётчик	Запросы, отклонённые в режиме enforce (метки: reason)
mcp_prometheus_guardrail_fail_open_total	Счётчик	Запросы, пропущенные при недоступности включённой оценки (метки: reason)

reason принимает значение selector, range, points или cardinality для would_block и blocked; запрос учитывается один раз по первой не пройденной проверке в этом порядке. Для fail_open используется unparseable или cardinality_unknown. Необязательная политика кардинальности использует кэшированную статистику TSDB top-N, чтобы требовать явного ограничения области для известных метрик с высокой кардинальностью; она не оценивает выбранные ряды и не доказывает безопасность отсутствующих метрик. Если конечные точки TSDB не поддерживаются, эта политика пропускает запросы. Метки backend нет.

Встраивающим библиотеку следует задавать GrafanaConfig.MeterProvider (аналог метрик для GrafanaConfig.Logger): ограничитель работает внутри обработчика инструмента, поэтому у него нет параметра конструктора, а процесс, устанавливающий глобальный MeterProvider бездействующего типа, иначе отбросит все записи.

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

Флаг --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	Значение ошибки, если запрос завершился с ошибкой (контекст предоставляется по возможности; содержимое определяется обёрткой ошибки вышестоящего компонента)
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: для этого укажите удалённую конечную точку gRPC в OTEL_EXPORTER_OTLP_LOGS_ENDPOINT (или общем параметре OTEL_EXPORTER_OTLP_ENDPOINT) и передайте данные аутентификации через 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

Принудительное применение ограничений к запросам Prometheus

--prometheus-enforced-matchers позволяет оператору ограничить набор рядов Prometheus, доступных для чтения встроенным инструментам Prometheus: фиксированный набор селекторов меток PromQL добавляется через AND к каждому векторному селектору во всех запросах к Prometheus, отправляемых сервером. Это полезно, если источник данных содержит ряды, которые нельзя раскрывать (например, метрики с конфиденциальными метками арендаторов или клиентов), но ограничить доступ на уровне Prometheus невозможно.

# Only ever read prod/staging environments (allowlist)
./mcp-grafana --prometheus-enforced-matchers 'environment=~"prod|staging"' --disable-api --disable-rendering --disable-assistant

# Never read the vault or payments namespaces (exclusion)
./mcp-grafana --prometheus-enforced-matchers 'namespace!~"vault|payments"' --disable-api --disable-rendering --disable-assistant

Как это работает:

• Селекторы разбираются один раз при запуске (при некорректном вводе запуск сервера прерывается) и добавляются к каждому векторному селектору в каждом запросе. Пользовательский запрос может только сужать результаты в пределах заданных ограничений — расширить их невозможно.
• Ограничение распространяется на query_prometheus, query_prometheus_histogram и панели Prometheus в run_panel_query.
• При обнаружении данных Prometheus через list_prometheus_label_names, list_prometheus_label_values и list_prometheus_metric_names селекторы также применяются к каждому селектору рядов, в том числе если селектор не указан.
• Использование list_prometheus_metric_metadata запрещено, пока действует ограничение: конечная точка метаданных Prometheus не может фильтровать данные по меткам рядов и объединяет метаданные разных целей. Обнаружение данных Cloud Monitoring также запрещено, поскольку его API обнаружения не поддерживают применение всей политики селекторов Prometheus.
• Применяется принцип безопасного отказа: любой запрос, который не удаётся разобрать, отклоняется, а не отправляется без фильтрации.

[!IMPORTANT] Другие включённые инструменты могут обходить эти селекторы. Отключите grafana_api_request с помощью --disable-api, инструменты рендеринга с помощью --disable-rendering и Grafana Assistant с помощью --disable-assistant (или --disable-write). В частности, render_grafana_app может отправлять нефильтрованные запросы Prometheus через источник query_datasource. --disable-dsquery закрывает этот источник, но не отключает рендеринг панелей на стороне сервера. Существующие снимки дашбордов также могут содержать неограниченные данные; если это важно, используйте --disable-snapshot.

Принудительное применение ограничений к запросам Loki

--loki-enforced-matchers позволяет оператору ограничить набор потоков логов Loki, доступных серверу: фиксированный набор селекторов меток LogQL добавляется через AND ко всем запросам к встроенному Loki, отправляемым сервером. Это полезно, если источник данных содержит потоки, которые нельзя раскрывать (например, логи с конфиденциальной информацией), но ограничить доступ на уровне Grafana или Loki невозможно (в OSS нет управления доступом к меткам на уровне источника данных или пользователя).

# Only ever read prod/staging environments (allowlist)
./mcp-grafana --loki-enforced-matchers 'environment=~"prod|staging"' --disable-api

# Never read the vault or payments namespaces (exclusion)
./mcp-grafana --loki-enforced-matchers 'namespace!~"vault|payments"' --disable-api

Как это работает:

• Селекторы разбираются один раз при запуске (при некорректном вводе запуск сервера прерывается) и добавляются к каждому селектору потока в каждом запросе. Поскольку Loki объединяет селекторы через AND внутри селектора, пользовательский запрос может только сужать результаты в пределах заданных ограничений — расширить их невозможно. Если пользовательский селектор противоречит политике (например, запрашивает {namespace="vault"} при действующем исключении), результатом будет пустой набор.
• Ограничение распространяется на query_loki_logs, query_loki_stats, query_loki_patterns, list_loki_label_names и list_loki_label_values.
• Применяется принцип безопасного отказа: любой запрос, который не удаётся разобрать, отклоняется, а не отправляется без фильтрации.
• Источники данных VictoriaLogs используют LogsQL, который нельзя безопасно переписать, поэтому при включённом ограничении они полностью запрещены.
• Селекторы, содержащие только отрицательные условия, не могут ограничить конечные точки перечисления меток (Loki отклоняет отдельный селектор без положительного условия). Управляйте этим особым случаем с помощью --loki-label-enumeration-fallback (reject по умолчанию или unfiltered, чтобы разрешить перечисление метаданных меток без ограничений — строки логов при этом никогда не раскрываются). Положительные селекторы и селекторы по списку разрешённых значений не затрагиваются.

[!IMPORTANT] Ограничение применяется только к инструментам запросов Loki. Другие инструменты могут получать данные логов Loki по путям, которые не проходят через ограничиваемый бэкенд. Поэтому, чтобы ограничение действительно действовало, необходимо также отключить эти инструменты:

• --disable-api — grafana_api_request может напрямую обращаться к прокси источника данных Loki (полный обход).
• --disable-rendering — get_panel_image выполняет рендеринг панелей Loki на стороне сервера, создавая изображения с неограниченными строками логов.
• --disable-assistant — ask_assistant делегирует запросы Grafana Assistant, который читает данные Loki на стороне сервера из всех потоков. Инструмент регистрируется только при включённых инструментах записи, поэтому --disable-write также отключает его.

При запуске сервер записывает предупреждение с названиями всех таких инструментов, которые остались включёнными. run_panel_query безопасен (он использует тот же путь запросов с ограничениями). Инструменты Tempo запрашивают трейсы, а не логи Loki, поэтому обойти ограничение через них нельзя. Снимки дашбордов (--disable-snapshot) также могут содержать данные панелей логов, полученные вне действия ограничения.

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

Совместимость с версиями 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 или новее.

Разработка

Мы приветствуем вклад в проект! Сначала прочитайте CONTRIBUTING.md — там описано, что относится к этому серверу и как предложить изменения.

Если вы добавляете новый инструмент, сначала предложите его, прежде чем писать код. Каждый инструмент, включённый по умолчанию, отправляется модели при каждом запросе от каждого пользователя, поэтому мы предпочитаем обсудить идею заранее, а не отклонять готовый pull request. Для исправлений ошибок, документации, тестов и новых параметров существующих инструментов предложение не требуется — просто отправьте PR.

Проект написан на Go. Версии инструментов и задачи разработки указаны в mise.toml: установите mise, выполните mise install, чтобы получить закреплённые версии инструментов, и mise tasks, чтобы вывести список задач.

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

mise run run

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

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

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

mise run build-image

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

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

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

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

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

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

1. Модульные тесты (внешние зависимости не требуются):

mise run test-unit

Модульные тесты также можно запустить командой:

mise run test

2. Интеграционные тесты (требуют запущенных контейнеров Docker):

mise run test-integration

3. Облачные тесты (требуют экземпляр Grafana Cloud и учётные данные):

mise run test-cloud

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

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

docker-compose up -d

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

Проверка стиля кода

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

mise run lint

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

mise run lint-jsonschema

Подробнее см. в документации по линтеру JSONSchema.

Лицензия

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