Grafana

официальный

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

GitHub

3.5k

Попробовать этот MCPСпонсировано

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

Поиск и просмотр дашбордов — Запрашивайте дашборды по названию, папке, тегу или статусу избранного, затем получайте сводки, версии или конкретные свойства JSONPath, такие как $.title, через search_dashboards, get_dashboard_summary или get_dashboard_property.
Запросы к Prometheus и Loki — Выполняйте запросы PromQL или LogQL, получайте метаданные метрик и меток, а также вычисляйте процентили гистограмм (p50–p99) напрямую из ваших источников данных.
Управление алертами и инцидентами — Просматривайте или создавайте правила алертов, проверяйте статусы срабатывания, а также ищите или обновляйте записи Grafana Incident с пользовательскими полями.
Изучение данных SQL и CloudWatch — Просматривайте таблицы, описывайте схемы и выполняйте SQL-запросы с макросами в ClickHouse, Snowflake, Athena, MySQL, PostgreSQL или MSSQL; также запрашивайте метрики CloudWatch по пространству имен и измерению.
Рендеринг дашбордов и создание ссылок — Получайте панель или дашборд в виде PNG-изображения или создавайте точные глубокие ссылки на дашборды, панели и Explore с временными диапазонами и переменными.

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

Сервер Grafana MCP

Сервер Model Context Protocol (MCP) для Grafana.

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

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

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

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

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

Требования

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

Возможности

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

Панели мониторинга

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

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

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

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

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

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

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

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

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

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

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

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

Запросы к Prometheus

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

Запросы к Loki

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

Запросы к InfluxDB

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

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

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

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

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

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

Запросы к CloudWatch

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

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

Запросы к Google Cloud Logging

Примечание: Инструменты Google Cloud Logging отключены по умолчанию. Чтобы включить их, добавьте cloudlogging к вашему флагу --enabled-tools. Требуется плагин источника данных Google Cloud Logging (googlecloud-logging-datasource) версии 1.8.0 или новее, для которого требуется 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 рендеринга Graphite к источнику данных 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-разговоров или их поиск с помощью выражения фильтра (модель, провайдер, агент, статус, тип ошибки, результаты оценки и другое) за определенный период времени. Результаты поиска включают количество ошибок, сводки рейтингов, сводки оценок и идентификаторы трассировок.
Получение деталей разговора: Получение одного разговора со всеми его генерациями, включая промпты и выходные данные.
Получение деталей генерации и оценок: Получение одной генерации по идентификатору и ее оценок (оценщик, ключ оценки, значение, пройдено, объяснение).
Чтение каталога агентов: Список агентов, отправляющих телеметрию, получение полной версии одного агента (полный системный промпт, каждый инструмент с его JSON-схемой и модели, на которых он работал), просмотр истории версий агента и сравнение агрегированных оценок по версиям. Эффективные версии — это sha256: хэши, на которые изменение инструмента никогда не влияет; для агента, не сообщающего собственную версию, они хэшируют системный промпт, поэтому изменение промпта создает новую версию. Строки каталога и версий содержат token_estimate, который стоит проверить перед получением полного промпта.
Просмотр оценщиков и шаблонов: Чтение оценщиков, из которых получена оценка, шаблонов, на основе которых они созданы, а также провайдеров и моделей судей, доступных для LLM-оценщиков. С включенными инструментами записи также можно создавать, форкать, тестировать и удалять оценщиков.
Просмотр правил оценки и защит: Чтение асинхронных правил оценки, связывающих оценщиков с производственным трафиком, и защит (правил-хуков), которые выполняются встроенно и могут предупреждать или запрещать. С включенными инструментами записи также можно создавать, обновлять, просматривать и удалять их. Записи и непостоянные операции preview_rule и test_evaluator требуют разрешения grafana-agento11y-app.eval:write, предоставляемого ролью администратора Agento11y.
Курирование сохраненных разговоров и коллекций: Чтение сохраненных разговоров (закладок, дающих разговору стабильный идентификатор, имя и теги) и коллекций, которые их группируют, включая количество участников каждой коллекции и коллекции, встроенные в каждую строку сохраненного разговора. С включенными инструментами записи также можно добавить разговор в закладки, создавать и редактировать коллекции, добавлять или удалять участников. Эти записи требуют того же разрешения 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. Они также являются инструментами записи (ассистент может изменять состояние стека), поэтому пропускаются, когда установлен --disable-write. Чтобы включить их, добавьте assistant в ваш флаг --enabled-tools.

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

Инциденты

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

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

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

Оповещения

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

Grafana OnCall

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

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

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

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

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

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

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

Аннотации

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

Снимки

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

Рендеринг

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

Подготовка

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

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

Разрешения RBAC

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

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

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

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

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

Области RBAC

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

Общие шаблоны областей:

Широкий доступ: Используйте подстановочные знаки * для доступа на уровне всей организации
- datasources:* - Доступ ко всем источникам данных
- dashboards:* - Доступ ко всем дашбордам
- folders:* - Доступ ко всем папкам
- teams:* - Доступ ко всем командам
Ограниченный доступ: Используйте конкретные UID или ID для ограничения доступа к отдельным ресурсам
- datasources:uid:prometheus-uid - Доступ только к конкретному источнику данных Prometheus
- dashboards:uid:abc123 - Доступ только к дашборду с UID abc123
- folders:uid:xyz789 - Доступ только к папке с UID xyz789
- teams:id:5 - Доступ только к команде с ID 5
- global.users:id:123 - Доступ только к пользователю с ID 123

Примеры:

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

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

Ограниченный доступ к источникам данных: Запросы только к конкретным экземплярам Prometheus и Loki
```
datasources:uid:prometheus-prod (datasources:query)
datasources:uid:loki-prod (datasources:query)
```
Доступ к конкретным дашбордам: Чтение только определенных дашбордов
```
dashboards:uid:monitoring-dashboard (dashboards:read)
dashboards:uid:alerts-dashboard (dashboards:read)
```

Инструменты

Инструмент	Категория	Описание	Требуемые разрешения RBAC	Требуемые области действия
`list_teams`	Администрирование	Список всех команд	`teams:read`	`teams:*` или `teams:id:1`
`list_users_by_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`	`roles:uid:editor`
`list_user_roles`	Администрирование	Список ролей для пользователей	`roles:read`	`global.users:id:123`
`list_team_roles`	Администрирование	Список ролей для команд	`roles:read`	`teams:id:7`
`get_resource_permissions`	Администрирование	Список разрешений для ресурса	`permissions:read`	`dashboards:uid:abcd1234`
`get_resource_description`	Администрирование	Описание типа ресурса Grafana	`permissions:read`	`dashboards:*`
`user_info`	Пользователь	Текущая личность, возможности и доступные организации	Нет (вошедший пользователь)	—
`search_dashboards`	Поиск	Поиск панелей мониторинга по запросу, UID папки, тегу или избранному	`dashboards:read`	`dashboards:*` или `dashboards:uid:abc123`
`get_dashboard_by_uid`	Панель мониторинга	Получение панели мониторинга по uid, при необходимости сохраненной версии	`dashboards:read`	`dashboards:uid:abc123`
`list_dashboard_versions`	Панель мониторинга	Список сохраненных версий панели мониторинга (версия, автор, время, сообщение)	`dashboards:read`	`dashboards:uid:abc123`
`update_dashboard`	Панель мониторинга	Обновление или создание новой панели мониторинга	`dashboards:create`, `dashboards:write`	`dashboards:`, `folders:` или `folders:uid:xyz789`
`get_dashboard_panel_queries`	Панель мониторинга	Получение заголовка панели, запросов, UID источника данных и типа из панели мониторинга	`dashboards:read`	`dashboards:uid:abc123`
`run_panel_query`	Выполнение запроса панели*	Выполнение одного или нескольких запросов панели мониторинга	`dashboards:read`, `datasources:query`	`dashboards:uid:`, `datasources:uid:`
`get_dashboard_property`	Панель мониторинга	Извлечение определенных частей панели мониторинга с помощью выражений JSONPath	`dashboards:read`	`dashboards:uid:abc123`
`get_dashboard_summary`	Панель мониторинга	Получение компактного сводного описания панели мониторинга без полного JSON	`dashboards:read`	`dashboards:uid:abc123`
`list_datasources`	Источники данных	Список источников данных	`datasources:read`	`datasources:*`
`get_datasource`	Источники данных	Получение источника данных по UID или имени	`datasources:read`	`datasources:uid:prometheus-uid`
`get_query_examples`	Примеры*	Получение примеров запросов для типа источника данных	`datasources:read`	`datasources:*`
`query_prometheus`	Prometheus	Выполнение запроса к источнику данных Prometheus	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_metric_metadata`	Prometheus	Список метаданных метрик	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_metric_names`	Prometheus	Список доступных имен метрик	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_label_names`	Prometheus	Список имен меток, соответствующих селектору	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_label_values`	Prometheus	Список значений для конкретной метки	`datasources:query`	`datasources:uid:prometheus-uid`
`query_prometheus_histogram`	Prometheus	Расчет процентильных значений гистограммы	`datasources:query`	`datasources:uid:prometheus-uid`
`list_incidents`	Инцидент	Список инцидентов в Grafana Incident, при необходимости с их значениями пользовательских полей	Роль просмотра	Н/Д
`create_incident`	Инцидент	Создание инцидента в Grafana Incident, при необходимости с установкой пользовательских полей	Роль редактора	Н/Д
`add_activity_to_incident`	Инцидент	Добавление элемента активности в инцидент в Grafana Incident	Роль редактора	Н/Д
`update_incident`	Инцидент	Обновление инцидента в Grafana Incident (статус, серьезность, заголовок или пользовательские поля)	Роль редактора	Н/Д
`get_incident`	Инцидент	Получение одного инцидента по ID, включая его пользовательские поля	Роль просмотра	Н/Д
`list_incident_custom_fields`	Инцидент	Список пользовательских полей, настроенных для инцидентов, с их типами и параметрами выбора	Роль просмотра	Н/Д
`query_loki_logs`	Loki	Запрос и получение журналов с помощью LogQL (либо журнальные, либо метрические запросы)	`datasources:query`	`datasources:uid:loki-uid`
`list_loki_label_names`	Loki	Список всех доступных имен меток в журналах	`datasources:query`	`datasources:uid:loki-uid`
`list_loki_label_values`	Loki	Список значений для конкретной метки журнала	`datasources:query`	`datasources:uid:loki-uid`
`query_loki_stats`	Loki	Получение статистики о потоках журналов	`datasources:query`	`datasources:uid:loki-uid`
`query_loki_patterns`	Loki	Запрос обнаруженных шаблонов журналов для выявления общих структур	`datasources:query`	`datasources:uid:loki-uid`
`analyze_loki_labels`	Loki	Аудит стратегии меток Loki (динамическая или статическая) и при необходимости диагностика производительности запросов	`datasources:query`	`datasources:uid:loki-uid`
`suggest_loki_alloy_label_config`	Конфигурация	Создание фрагмента Alloy `loki.process`, обеспечивающего соблюдение утвержденных меток	Н/Д	Н/Д
`query_influxdb`	InfluxDB	Запросы к InfluxDB с использованием InfluxQL (v1) или Flux (v2)	`datasources:query`	`datasources:uid:influxdb-uid`
`list_sql_databases`	SQL*	Список баз данных, схем или каталогов из источника данных SQL	`datasources:query`	`datasources:uid:*`
`list_sql_tables`	SQL*	Список таблиц в источнике данных SQL	`datasources:query`	`datasources:uid:*`
`describe_sql_table`	SQL*	Получение схемы столбцов для таблицы	`datasources:query`	`datasources:uid:*`
`query_sql`	SQL*	Выполнение SQL-запросов с подстановкой макросов	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_namespaces`	CloudWatch*	Список доступных пространств имен AWS CloudWatch	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_metrics`	CloudWatch*	Список метрик в пространстве имен	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_dimensions`	CloudWatch*	Список измерений для метрики	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_dimension_values`	CloudWatch*	Список значений для ключа измерения	`datasources:query`	`datasources:uid:*`
`query_cloudwatch`	CloudWatch*	Выполнение запросов метрик CloudWatch	`datasources:query`	`datasources:uid:*`
`list_cloud_logging_projects`	Cloud Logging*	Список проектов GCP, доступных для чтения источником данных Google Cloud Logging	`datasources:query`	`datasources:uid:*`
`list_cloud_logging_buckets`	Cloud Logging*	Список журнальных сегментов в проекте GCP	`datasources:query`	`datasources:uid:*`
`list_cloud_logging_views`	Cloud Logging*	Список представлений журналов в журнальном сегменте	`datasources:query`	`datasources:uid:*`
`query_cloud_logging`	Cloud Logging*	Запросы к журналам с использованием языка запросов Cloud Logging	`datasources:query`	`datasources:uid:*`
`query_elasticsearch`	Elasticsearch/OpenSearch*	Запросы к Elasticsearch или OpenSearch с использованием синтаксиса Lucene или Query DSL	`datasources:query`	`datasources:uid:datasource-uid`
`query_quickwit`	Quickwit*	Запросы к Quickwit с использованием синтаксиса Lucene или Query DSL	`datasources:query`	`datasources:uid:quickwit-uid`
`alerting_manage_rules`	Alerting	Управление правилами оповещений (список, получение, версии, создание, обновление, удаление)	`alert.rules:read` + `alert.rules:write` для изменений	`folders:*` или `folders:uid:alerts-folder`
`alerting_manage_routing`	Alerting	Управление политиками уведомлений, контактными точками и временными интервалами	`alert.notifications:read`	Глобальная область
`alerting_manage_silences`	Alerting	Управление периодами тишины оповещений (список, получение, создание, обновление, завершение)	`alert.instances:read` + `alert.instances:write` для изменений	Глобальная область
`list_oncall_schedules`	OnCall	Список расписаний из Grafana OnCall	`grafana-oncall-app.schedules:read`	Области, специфичные для плагина
`get_oncall_shift`	OnCall	Получение сведений о конкретной смене OnCall	`grafana-oncall-app.schedules:read`	Области, специфичные для плагина
`get_current_oncall_users`	OnCall	Получение пользователей, находящихся на дежурстве для конкретного расписания	`grafana-oncall-app.schedules:read`	Области, специфичные для плагина
`list_oncall_teams`	OnCall	Список команд из Grafana OnCall	`grafana-oncall-app.user-settings:read`	Области, специфичные для плагина
`list_oncall_users`	OnCall	Список пользователей из Grafana OnCall	`grafana-oncall-app.user-settings:read`	Области, специфичные для плагина
`list_alert_groups`	OnCall	Список групп оповещений из Grafana OnCall с параметрами фильтрации	`grafana-oncall-app.alert-groups:read`	Области, специфичные для плагина
`get_alert_group`	OnCall	Получение конкретной группы оповещений из Grafana OnCall по её идентификатору	`grafana-oncall-app.alert-groups:read`	Области, специфичные для плагина
`update_alert_group`	OnCall	Подтверждение, отмена подтверждения, разрешение или отмена разрешения группы оповещений	`grafana-oncall-app.alert-groups:write` (и `:read`)	Области, специфичные для плагина
`get_sift_investigation`	Sift	Получение существующего расследования Sift по его UUID	Роль просмотра	Н/Д
`get_sift_analysis`	Sift	Получение конкретного анализа из расследования Sift	Роль просмотра	Н/Д
`list_sift_investigations`	Sift	Получение списка расследований Sift с необязательным ограничением	Роль просмотра	Н/Д
`find_error_pattern_logs`	Sift	Находит повышенные шаблоны ошибок в журналах Loki.	Роль редактора	Н/Д
`find_slow_requests`	Sift	Находит медленные запросы из соответствующих источников данных tempo.	Роль редактора	Н/Д
`list_pyroscope_label_names`	Pyroscope	Список имен меток, соответствующих селектору	`datasources:query`	`datasources:uid:pyroscope-uid`
`list_pyroscope_label_values`	Pyroscope	Список значений меток, соответствующих селектору для имени метки	`datasources:query`	`datasources:uid:pyroscope-uid`
`list_pyroscope_profile_types`	Pyroscope	Список доступных типов профилей	`datasources:query`	`datasources:uid:pyroscope-uid`
`query_pyroscope`	Pyroscope	Запросы профилей, метрик или того и другого из Pyroscope	`datasources:query`	`datasources:uid:pyroscope-uid`
`get_assertions`	Asserts	Получение сводки утверждений для заданной сущности	Разрешения, специфичные для плагина	Области, специфичные для плагина
`agento11y_manage_conversations`	Agent Observability*	Список, поиск и получение LLM-разговоров из Grafana Agent Observability	`grafana-agento11y-app.conversations:read`	Н/Д
`agento11y_manage_generations`	Agent Observability*	Получение деталей генерации LLM и оценок из Grafana Agent Observability	`grafana-agento11y-app.data:read`	Н/Д
`agento11y_manage_agents`	Agent Observability*	Чтение каталога агентов: список агентов, получение полной версии одного агента, история версий и агрегированные оценки по версиям	`grafana-agento11y-app.data:read`	Н/Д
`agento11y_manage_evaluators`	Agent Observability*	Управление оценщиками, шаблонами оценщиков и каталогом судей (список, получение, обновление, форк, тест, удаление)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` для изменений и тестов	Н/Д
`agento11y_manage_eval_rules`	Agent Observability*	Управление правилами оценки и защитами (список, получение, создание, обновление, предпросмотр, удаление)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` для изменений и предпросмотров	Н/Д
`agento11y_manage_eval_collections`	Agent Observability*	Управление сохраненными разговорами и коллекциями, которые их группируют (список, получение, сохранение, создание, обновление, удаление, добавление и удаление участников)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` для изменений	Н/Д
`agento11y_manage_experiments`	Наблюдаемость агентов*	Чтение офлайн-экспериментов, их испытаний, оценок, метаданных артефактов и фильтрующих аспектов; обновление и отмена эксперимента	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` для изменений	Н/Д
`agento11y_manage_test_suites`	Наблюдаемость агентов*	Управление наборами тестов, против которых выполняются офлайн-эксперименты, их версиями и тестовыми случаями (список, получение, создание, обновление, черновик, публикация, апсерт, удаление)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` для изменений	Н/Д
`ask_assistant`	Ассистент*	Отправка запроса Grafana Assistant и возврат полного текстового ответа (многоходовой через `contextId`)	Права, специфичные для плагина	Области, специфичные для плагина
`generate_deeplink`	Навигация	Генерация точных deep-link URL-адресов для ресурсов Grafana	Нет (генерация URL только для чтения)	Н/Д
`get_annotations`	Аннотации	Получение аннотаций с фильтрами	`annotations:read`	`annotations:*` или `annotations:id:123`
`create_annotation`	Аннотации	Создание новой аннотации (стандартный или формат Graphite)	`annotations:write`	`annotations:*`
`update_annotation`	Аннотации	Обновление конкретных полей аннотации (частичное обновление)	`annotations:write`	`annotations:*`
`delete_annotation`	Аннотации	Удаление аннотации по ID	`annotations:delete`	`annotations:*`
`get_annotation_tags`	Аннотации	Список тегов аннотаций с необязательной фильтрацией	`annotations:read`	`annotations:*`
`list_snapshots`	Снимок	Список снимков панелей мониторинга с необязательными фильтрами запроса и лимита	`dashboards:read`	`dashboards:*` или `dashboards:uid:abc123`
`get_snapshot`	Снимок	Получение метаданных снимка и полезной нагрузки панели мониторинга по ключу снимка	`dashboards:read`	`dashboards:*` или `dashboards:uid:abc123`
`create_snapshot`	Снимок	Создание снимка панели мониторинга из полной полезной нагрузки панели мониторинга	`dashboards:write`	`dashboards:*` или `dashboards:uid:abc123`
`delete_snapshot`	Снимок	Удаление снимка панели мониторинга по ключу снимка	`dashboards:write`	`dashboards:*` или `dashboards:uid:abc123`
`get_panel_image`	Рендеринг	Рендеринг сохраненной панели мониторинга или панели — или предварительного просмотра из ветки репозитория — как PNG-изображения	`dashboards:read`	`dashboards:uid:abc123`
`list_provisioning_repositories`	Подготовка	Список репозиториев подготовки (например, источников git-sync) с их исходным URL, веткой, состоянием синхронизации и работоспособностью	`provisioning.repositories:read`	Н/Д
`validate_provisioning_file`	Подготовка	Пробное применение файла из репозитория подготовки и сообщение об ошибках проверки допуска	`provisioning.repositories:read`	Н/Д
`search_docs`	Документация	Поиск документации Grafana или список групп продуктов (опустите запрос для списка продуктов)	Нет (публичные grafana.com/docs)	Н/Д
`get_doc`	Документация	Получение страницы документации; установите outline_only для заголовков или section для ограниченного извлечения	Нет (публичные grafana.com/docs)	Н/Д
* Отключено по умолчанию. Добавьте категорию в `--enabled-tools`, чтобы включить.

Справочник по флагам 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
--server-name: Имя сервера, используемое в рукопожатии MCP и OTel service.name — по умолчанию: mcp-grafana. Переопределяет переменную окружения GRAFANA_MCP_SERVER_NAME
--instructions-append: Текст, добавляемый к инструкциям сервера, возвращаемым MCP-клиентам при инициализации, чтобы каждый подключающийся агент его видел

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

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

--allowed-hosts: Разделённый запятыми список разрешённых значений заголовка Host. По умолчанию — loopback-варианты --address (например, 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; отключено по умолчанию. Без списка разрешённых вызывающие могут выбрать любой HTTP(S) URL, доступный серверу.
--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 не затрагиваются); в будущем крупном релизе это станет ошибкой запуска. Используйте TLS (или завершение TLS) всякий раз, когда аутентификация вызывающего включена на не-loopback адресе. Когда аутентификация вызывающего включена, проверенный заголовок Authorization удаляется до того, как запросы достигнут Grafana; комбинация --server-auth-token с GRAFANA_FORWARD_HEADERS=Authorization отклоняется при запуске.

Переопределения URL Grafana (только SSE / 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 и учётных данных из окружения. Эта опция применяется только к SSE и streamable HTTP. Для SSE включайте оба заголовка выбора в каждый POST сообщения; заголовки на начальном SSE GET не переносятся на вызовы инструментов.

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

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

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

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

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

--metrics: Включить конечную точку метрик Prometheus на /metrics
--metrics-address: Отдельный адрес для сервера метрик (например, :9090). Если пусто, метрики обслуживаются на основном сервере
--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; любое нераспознанное значение отключает отчёт. См. раздел Анонимная статистика использования.

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

--session-idle-timeout-minutes: Тайм-аут простоя сеанса в минутах. Сеансы без активности в течение этой длительности автоматически завершаются — по умолчанию: 30. Установите 0, чтобы отключить завершение сеансов. Актуально только для SSE и streamable-http транспортов. Конфигурация инструментов:
--enabled-tools: Список включенных категорий через запятую — по умолчанию: все категории, кроме admin, agento11y, assistant, athena, clickhouse, cloudlogging, cloudwatch, elasticsearch, examples, graphite, quickwit, runpanelquery и snowflake. Чтобы включить отключенные категории, добавьте их в список (например, "search,datasource,...,snowflake")
--max-loki-log-limit: Максимальное количество строк журнала, возвращаемых за один вызов query_loki_logs — по умолчанию: 100. Примечание: установите это значение как минимум на 1 ниже серверного max_entries_limit_per_query в Loki, чтобы обеспечить обнаружение усечения (инструмент внутренне запрашивает limit+1, чтобы определить, существуют ли дополнительные данные).
--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 ГиБ). 0 отключает проверку байтового бюджета. Резервный вариант через переменную окружения: GRAFANA_LOKI_GUARDRAIL_MAX_BYTES.
--loki-guardrail-max-range: Максимальный эффективный временной диапазон для одного вызова query_loki_logs, включая длительности диапазонных векторов — по умолчанию: 24h. Принимает строки длительности Go. 0 отключает проверку диапазона. Резервный вариант через переменную окружения: GRAFANA_LOKI_GUARDRAIL_MAX_RANGE.
--loki-enforced-matchers: Соответствия меток LogQL, объединяемые через AND в каждый нативный запрос Loki, чтобы ограничить, какие потоки журналов можно читать (например, environment=~"prod|staging"). Требует --disable-api. См. Принудительное применение запросов Loki.
--loki-label-enumeration-fallback: Что делают инструменты перечисления меток, когда отрицательные принудительные соответствия не могут их ограничить: reject (по умолчанию) или unfiltered. См. Принудительное применение запросов Loki.
--disable-search: Отключить инструменты поиска
--disable-datasource: Отключить инструменты источников данных
--disable-incident: Отключить инструменты инцидентов
--disable-prometheus: Отключить инструменты Prometheus
--disable-write: Отключить инструменты записи (операции создания/обновления)
--disable-query: Отключить инструменты запросов (инструменты, выполняющие запрос к источнику данных); инструменты метаданных и обнаружения остаются доступными
--enable-query: Сохранить инструменты запросов необработанного SQL (query_sql, query_influxdb) зарегистрированными даже при --disable-write. Эквивалентно --enable-write-tools=query_sql,query_influxdb; сохранено как сокращение для этого распространенного случая.
--enable-write-tools: Список отдельных имен инструментов через запятую, которые следует сохранить зарегистрированными даже при --disable-write, для инструментов, чье поведение записи достаточно ограничено, чтобы их можно было независимо включить обратно (например, find_error_pattern_logs,find_slow_requests). Не влияет на инструмент, чья целая категория отключена, например, через --disable-sift.
--disable-loki: Отключить инструменты Loki
--disable-elasticsearch: Отключить инструменты Elasticsearch и OpenSearch
--disable-quickwit: Отключить инструменты Quickwit
--disable-influxdb: Отключить инструменты InfluxDB
--disable-alerting: Отключить инструменты оповещения
--disable-dashboard: Отключить инструменты панелей мониторинга
--disable-oncall: Отключить инструменты OnCall
--disable-asserts: Отключить инструменты asserts
--disable-sift: Отключить инструменты sift
--disable-admin: Отключить инструменты администрирования
--disable-pyroscope: Отключить инструменты Pyroscope
--disable-navigation: Отключить инструменты навигации
--disable-rendering: Отключить инструменты рендеринга (экспорт изображений панелей/панелей мониторинга)
--disable-snapshot: Отключить инструменты снимков
--disable-cloudwatch: Отключить инструменты CloudWatch
--disable-cloudlogging: Отключить инструменты Google Cloud Logging
--disable-examples: Отключить инструменты примеров запросов
--disable-sql: Отключить инструменты источников данных SQL (ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, MSSQL). Псевдонимы --disable-clickhouse, --disable-snowflake, --disable-athena также работают.
--disable-runpanelquery: Отключить инструменты запросов панелей запуска
--disable-graphite: Отключить инструменты Graphite
--disable-provisioning: Отключить инструменты предоставления
--disable-agento11y: Отключить инструменты наблюдаемости агентов
--disable-assistant: Отключить инструменты Grafana Assistant
--disable-docs: Отключить инструменты документации

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

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

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

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

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

update_dashboard

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

create_folder

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

create_incident
add_activity_to_incident
update_incident

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

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

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

update_alert_group

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

create_annotation
update_annotation
delete_annotation

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

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

Они только создают временные записи расследований Sift через API Sift — они никогда не касаются панелей мониторинга, оповещений или источников данных Grafana. Без них list_sift_investigations/get_sift_investigation/get_sift_analysis нечего перечислять или получать. Передайте --enable-write-tools=find_error_pattern_logs,find_slow_requests, чтобы сохранить их зарегистрированными при --disable-write.

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

create_snapshot
delete_snapshot

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

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

query_sql
query_influxdb

Инструменты наблюдаемости агентов:

agento11y_manage_evaluators (операции upsert, delete, fork, test evaluator)
agento11y_manage_eval_rules (операции create, update, delete, preview rule и guard)
agento11y_manage_eval_collections (сохранение и удаление сохраненных разговоров; создание, обновление, удаление коллекций; добавление и удаление участников коллекций)
agento11y_manage_experiments (операции update и cancel experiment)
agento11y_manage_test_suites (создание и обновление тестовых наборов; создание и публикация версий; upsert и удаление тестовых случаев)

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

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

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

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

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

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

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

query_prometheus
query_prometheus_histogram

Инструменты 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

Инструменты 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 к grafana_api_request через /api/ds/query, но не контролирует каждый маршрут к источнику данных. В режиме только для чтения 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: Путь к файлу сертификата CA 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 в примерах конфигурации ниже.

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

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

Динамический (по вызову) выбор организации

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

Когда он включен, каждый инструмент принимает необязательный аргумент orgId, который переопределяет организацию соединения для этого вызова (управляя как заголовком X-Grafana-Org-Id, так и, для API платформы приложений, разрешенным Kubernetes namespace). Проксируемые инструменты источников данных дополнительно обнаруживаются во всех организациях, к которым имеет доступ учетная запись. Вызовы, опускающие 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-заголовки

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

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

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

SOCKS5 прокси

Вы можете маршрутизировать все запросы этого сервера к Grafana через SOCKS5 прокси, используя переменную окружения GRAFANA_SOCKS5_PROXY. Прокси ограничен трафиком этого сервера к 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 напрямую.

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

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

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

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

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

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

GRAFANA_FORWARD_HEADERS=Cookie,X-Session-Id

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

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

У вас есть несколько вариантов установки mcp-grafana:
- uvx (рекомендуется): Если у вас установлен uv, дополнительная настройка не требуется — uvx автоматически загрузит и запустит сервер:
```
uvx mcp-grafana
```
- Docker-образ: Используйте готовый Docker-образ из Docker Hub.
  
  Важно: Точка входа Docker-образа настроена на запуск MCP-сервера в режиме SSE по умолчанию, но большинству пользователей потребуется режим STDIO для прямой интеграции с ИИ-ассистентами, такими как Claude Desktop:
  1. Режим STDIO: Для режима stdio вы должны явно переопределить значение по умолчанию с помощью -t stdio и включить флаг -i, чтобы держать stdin открытым:
```
docker pull grafana/mcp-grafana
# For local Grafana:
docker run --rm -i -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio
# For Grafana Cloud:
docker run --rm -i -e GRAFANA_URL=https://myinstance.grafana.net -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio
```
  Примечание — защитите сетевые режимы: В режимах SSE и streamable-http контейнер привязывается к адресу, не являющемуся loopback (0.0.0.0:8000). Без токена вызывающего сервер запускается, но регистрирует ошибку безопасности (на уровне журнала error, поэтому она не скрывается --log-level; и он откажется запускаться в будущем крупном релизе). Установите MCP_GRAFANA_SERVER_TOKEN, чтобы требовать Authorization: Bearer <token> от клиентов (рекомендуется). Режим STDIO не затрагивается. См. Аутентификация вызывающего.
  1. Режим SSE: В этом режиме сервер работает как HTTP-сервер, к которому подключаются клиенты. Вы должны открыть порт 8000 с помощью флага -p:
```
docker pull grafana/mcp-grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> grafana/mcp-grafana
```
  1. Режим Streamable HTTP: В этом режиме сервер работает как независимый процесс, который может обрабатывать несколько клиентских соединений. Вы должны открыть порт 8000 с помощью флага -p: Для этого режима вы должны явно переопределить значение по умолчанию с помощью -t streamable-http
```
docker pull grafana/mcp-grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> grafana/mcp-grafana -t streamable-http
```
  Для HTTPS streamable HTTP режима с серверными TLS-сертификатами:
```
docker pull grafana/mcp-grafana
docker run --rm -p 8443:8443 \
  -v /path/to/certs:/certs:ro \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
  -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> \
  grafana/mcp-grafana \
  -t streamable-http \
  -addr :8443 \
  --server.tls-cert-file /certs/server.crt \
  --server.tls-key-file /certs/server.key
```
- Загрузка бинарного файла: Загрузите последний релиз mcp-grafana со страницы релизов и поместите его в ваш $PATH.
- Сборка из исходников: Если у вас установлен инструментарий Go, вы также можете собрать и установить его из исходников, используя переменную окружения GOBIN для указания каталога, куда должен быть установлен бинарный файл. Он также должен находиться в вашем $PATH.
```
GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest
```
- Развертывание в Kubernetes с помощью Helm: используйте Helm-чарт из репозитория helm-charts Grafana
```
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
```

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

--tls-cert-file: Путь к файлу TLS-сертификата для аутентификации клиента
--tls-key-file: Путь к файлу закрытого ключа TLS для аутентификации клиента
--tls-ca-file: Путь к файлу CA-сертификата 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-сервером, включая:

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

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

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

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

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

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

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

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

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

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

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

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

Проверка URL:

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

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

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

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

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

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

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

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

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

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

Пример Docker с серверным TLS:

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

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

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

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

Ответ:

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

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

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

# 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 или streamable HTTP транспортов. Она недоступна при использовании транспорта stdio (-t stdio), так как stdio не предоставляет HTTP-сервер.

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

Сервер может сообщать анонимную статистику использования о себе в Grafana Labs: какие инструменты вызывались, сколько из этих вызовов завершилось ошибкой и как настроен сервер. Один отчет охватывает один процесс сервера — не одного пользователя и не один разговор — и отправляется каждые 4 часа, а также один раз при завершении работы. В этом выпуске отправка отчетов отключена по умолчанию — принимающая конечная точка еще не активна — и в более позднем выпуске значение по умолчанию будет изменено на включенное с тем же механизмом отказа.

Аргументы инструментов, имена ресурсов, запросы, строки журнала, сообщения об ошибках и учетные данные никогда не отправляются. Флаги записываются только по имени, никогда по значению, а экземпляр 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 или streamable HTTP включите метрики Prometheus с помощью флага --metrics:

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

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

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

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

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

Когда включен защитный ограничитель стоимости 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.

Библиотечные встраиватели должны установить GrafanaConfig.MeterProvider (аналог метрик для GrafanaConfig.Logger): ограничитель работает внутри обработчика инструмента, поэтому у него нет опции конструктора, и процесс, который устанавливает глобальный noop 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 — указав OTEL_EXPORTER_OTLP_LOGS_ENDPOINT (или общий OTEL_EXPORTER_OTLP_ENDPOINT) на удаленную конечную точку gRPC и предоставив аутентификацию через OTEL_EXPORTER_OTLP_LOGS_HEADERS (или OTEL_EXPORTER_OTLP_HEADERS), как в примере с трассировкой выше. Локальный коллектор OTel необязателен — полезен для разветвления, пакетной обработки или маршрутизации на несколько бэкендов, но не требуется.

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

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

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

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

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

Принудительное применение запросов Loki

--loki-enforced-matchers позволяет оператору ограничить, какие потоки журналов Loki сервер может когда-либо читать, применяя фиксированный набор сопоставителей меток LogQL к каждому собственному запросу 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 для разрешения неограниченного перечисления метаданных меток — строки журналов никогда не раскрываются). Положительные/разрешающие сопоставители не затрагиваются.

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

--disable-api — grafana_api_request может запрашивать прокси источника данных Loki напрямую (полный обход).

--disable-rendering — get_panel_image отображает панели Loki на стороне сервера, создавая изображения с неограниченными строками журналов.

--disable-sift — расследования Sift анализируют журналы 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. Установите Go, следуя инструкциям для вашей платформы.

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

make run

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

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

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

make build-image

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

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

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

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

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

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

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

make test-unit

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

make test

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

make test-integration

Облачные тесты (требуют облачного экземпляра Grafana и учетных данных):

make test-cloud

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

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

docker-compose up -d

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

make test-all

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

Линтинг

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

make lint

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

make lint-jsonschema

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

Лицензия

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