Grafana MCP Server

MCP-сервер на базе Model Context Protocol (MCP), который предоставляет ИИ-ассистентам доступ только на чтение ко всему, что уже видит ваш Grafana: метрикам Prometheus/Loki, источникам данных ClickHouse/Postgres/MySQL и дашбордам, которые уже собрала ваша команда. Задавайте вопросы на естественном языке и получайте ответы, подтверждённые реальными данными.

Работает с Claude Code, Claude Desktop и любым MCP-совместимым клиентом. Ваш проект может быть на любом языке — этот сервер работает независимо.

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

Your project (any language)     grafana-mcp-server            Grafana            Datasources
┌───────────────────┐          ┌──────────────────┐          ┌──────────┐       ┌────────────┐
│  Claude Code or   │  stdio   │  Builds the      │  HTTPS   │ /api/ds/ │──────>│ Prometheus │
│  Claude Desktop   │────MCP──>│  per-plugin      │────────->│  query   │──────>│ ClickHouse │
│                   │<─────────│  query model     │<─────────│          │──────>│ Postgres … │
└───────────────────┘          └──────────────────┘          └──────────┘       └────────────┘

Сервер общается только с HTTP API Grafana. Grafana проксирует запрос к источнику данных со своими учётными данными, поэтому ассистент никогда не получает пароль базы данных, и видит ровно то, что видит пользователь Grafana, — не больше. Все запросы выполняются только на чтение (чтобы это было гарантировано, используйте учётные данные с ролью Viewer).

Related MCP server: Grafana MCP Server

Требования

• Node.js >= 18 или Docker (нужны только для запуска этого MCP-сервера)

• Учётная запись Grafana, в которую можно войти — Google / SSO / пароль, что бы ни использовал ваш Grafana. Права администратора, сервисный аккаунт и API-токен не требуются: grafana-mcp-server login выполнит вход в браузере и передаст сессию серверу (см. Аутентификация). Токен сервисного аккаунта тоже подойдёт, если он у вас есть.

• Установленный Chrome или Edge (используется только в качестве окна входа; ваш повседневный браузер может быть любым). Если ни одного из них нет, login переключится на пошаговоое копикопирование cookie в браузере по умолчанию.

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

Вариант A: Node.js

1. Клонируйте и соберите

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

В результате будет скомпилированнный ссервер по пути dist/main.js.

2. Войдите

GRAFANA_URL=https://grafana.example.com npm run login

Если Chrome или Edge установлены (как браузер по умолчанию или просто присутствют на машине — это подходит почти всем, каким бы ни был ваш повседневный браузер), login открывает его dedicated окно — с отдельным одноразовым, не вашим обычным, профилем — на странице входа в Grafana. Войдите так же, как делаете это всегда. В тот момент, когда Grafana выдаст сессию, команда сохранит её, удалит из профиля, проверит и выведет:

[grafana-mcp-server] ✓ signed in as jane <jane@example.com>

Ничего копировать, никаких токенов, ничего секретного в конфиг-файле. Если Grafana стоит за Cloudflare Access, вы входите в него в том же окне, и его cookie тоже будет захвачена. Не закрывайте и try to not close window until you see ✓. Сессия хранится в ~/.grafana-mcp/sessions/<host>.json (режим 600).

Playwright умеет управлять только Chrome/Chromium и Edge (Arc, например, вообще не автоматизируется), поэтому login использует один из них как окно входа, независимо от вашего браузера по умолчанию — ваш браузер по умолчанию никогда не затрагивается. Только если ни Chrome, ни Edge не установлены, login откроет Grafana в вашем браузере по умолчанию и под руководством — сделай это 개인적 копи grafana_session из DevTools.

Почему отдельное окно, а не моя открытая вкладка? Браузер никогда не передаёт свои cookie командной строке — эта изоляция и есть суть браузера, — поэтому login управляет своим экземпляром в отдельном профиле и забирает сессию из него.

Принудительно указать браузер: npm run login -- --browser chrome (или msedge, chromium после npx playwright install chromium, либо путь к Chromium-бинарнику). npm run login -- --paste читает cookie из stdin, не открывая браузера.

3. Настройка

Claude Code — одна команда, или эквивалентный блок .mcp.json:

claude mcp add grafana --scope user --env GRAFANA_URL=https://grafana.example.com -- node /home/john/grafana-mcp-server/dist/main.js

{
  "mcpServers": {
    "grafana": {
      "command": "node",
      "args": ["/home/john/grafana-mcp-server/dist/main.js"],
      "env": {
        "GRAFANA_URL": "https://grafana.example.com"
      }
    }
  }
}

Claude Desktop — тот же блок в конфигурационном файле:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Примечание: Замените /home/john/grafana-mcp-server на фактический путь, куда вы схлонировали репозиторий. Единственная обязательная настройка — GRAFANA_URL: учётные данные берётся из сессии, которую сохранил login. Перезапустите клиент после добавления сервера.

У вас токен сервисного аккаунта? Добавьте "GRAFANA_TOKEN": "glsa_…" в env и пропустите login. Или укажите GRAFANA_CREDENTIAL_FILE на файл с правами 0600, который его содержит, либо внедрите его из секрет-менеджера при запуске (например, charter secret exec … --exec -- node dist/main.js).

Вариант B: Docker

git clone https://github.com/stonoyan04/grafana-mcp-server.git
cd grafana-mcp-server
docker build -t grafana-mcp-server .

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/home/john/.grafana-mcp:/root/.grafana-mcp",
        "-e", "GRAFANA_URL=https://grafana.example.com",
        "grafana-mcp-server"
      ]
    }
  }
}

Запустите login на хост-машине (GRAFANA_URL=… npm run login из локальной копии Node, так как в контейнере нет браузера) и смонтируйте ~/.grafana-mcp в режиме чтения/записи, как это будут обновлённые сессии назад в контейнер. Либо вообще не монтируйте, а передайте -e GRAFANA_TOKEN=glsa_…, если у вас есть токен сервисного аккаунта.

Почему -i и не -t? MCP работает JSON по stdin/stdout. Ключ -i удерживает stdin открытым; TTY (-t) испортит поток.

Если Grafana за Cloudflare Access, смонтируйте свой хост-кэш токенов только для чтения — -v /home/john/.cloudflared:/root/.cloudflared:ro — и сначала выполните на хост-машине cloudflared access login https://grafana.example.com. Контейнер не может сам запускать cloudflared, поэтому он читает cмонтированный кэш (или CF_ACCESS_TOKEN); когда токен истечёт, снова выполните вход на хост-машине.

4. Исследуйте источники данных

List the Grafana datasources

Каждому инструменту запросов нужен uid источника данных, а тип источника данных определяет, какой инструмент использовать: query_metrics? напомню, для пострики, или: dashboards — (для): datasourceUid... На самом assemblage: query_sql for ClickHouse/Postgres/MySQL, query_metrics for Prometheus/Loki. list_datasources говорит и то и другое.

5. Начинайте задавать вопросы

How many messages per Kafka topic were produced in the last 7 days?   → query_metrics on Prometheus
Which dashboards mention "kafka"?                                     → search_dashboards
Show me the panel queries in that dashboard                           → get_dashboard
Run: SELECT count() FROM events WHERE created > now() - INTERVAL 1 DAY → query_sql on ClickHouse

Совет: get_dashboard возвращает необработанный SQL / PromQL за каждой панелью. Переиспользовать запрос, который человек уже написал и которому доверяет, лучше, чем писать с нуля.

Инструменты

Сервер предоставляет 6 инструментов только для чтения:

list_datasources

Выводит источники данных с uid, name, type и какой инструмент запросов применяется. Без параметров.

query_sql

Выполняет SQL-запрос к источником семейств данных через Grafana и получает строки.

Запрос, отправляемый в /api/ds/query, для каждого plugin grafana-clickhouse-datasource, datasource — vertamedia-clickhouse-datasource, а также для встроенных Postgres/MySQL/MSSQL — все используют разную схему.

query_metrics

Выполняет выражение PromQL или LogQL. Опустите параметр from для мгновенного запроса (instant query).

5... search_dashboards

1... get_dashboard

Возвращает все панели (flat rows), с каждой панелью — источник данных и сырой запрос, е variables, шаблонно переменные и default time range.

6... health

Проверяет связность и различает два слоя аутентификации: "failingLayer": "cloudflare" обозначает cloudflared access login (или повторите login); "failingLayer": "grafana" обозначает, что сохранённые сессия/учётные данные мертвы или имеют недостаточно прав — выполните grafana-mcp-server login. Сообщает, кем проходит учтетная запись, и количество доступных датабаз. Параметров нет. Вызовите его первым, если другой инструмент подряд отказал.

Data frames сплющиваются в простые строки, ключом поля (серия Prometheus дездамибируется по меткам), пределах до GRAFANA_MAX_ROWS.

Команды

npm run login / npm run logout выполняют то же самое из локальной копии проекта.

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

Вся конфигурация задаётся через переменные окружения. При использовании login достаточен только GRAFANA_URL.

Приоритет учётных данных: GRAFANA_TOKEN → GRAFANA_USERNAME+PASSWORD → GRAFANA_SSESSION → GRAFANA_CREDENTIAL_FILE → сессия, сохранённая login, → ~/.grafana-mcp-token, если он существует.

Разрешённый список источников данных

"ALLOWED_DATASOURCES": "OsirT4Bnz,Prometheus"

list_datasources скрывает всё остальное, а инстременты запросов отклоняют его.

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

Grafana: вход с вашей учётной записью (login)

grafana-mcp-server login обеспечивает вход в вашу учётную запись и уверяет сесию на сервер. Он управляет Chrom или Edge — темом, которая установна, и используется только как окно входа, независимо от вашего браузера по умолчанию — через Playwrite в отдельном профиле по ~/.grafana-mcp/browser, открывает GRAFANA_URL/login и ждёт, пока вы входимі — Google, GitHub, SAML, LDAAP или простой чоль; интрумент никогда не видит и не вводит ваши верите ля. Когда Grafana устанают свою cookie grafana_session, интрумент:

1. Копирует сиюсию (и cookie CF_Authorization, если перед Grafana есть Cloudflare Access) в ~/.grafana-mcp/sessions/<host>.json (0600),

2. удаляет cookies Grafana из этого браузерного профиля, поэтому сервис станет единственным держателем сессии,

3. вызывает на капиuser через собственную кодопую дорогу сервера и выполняет, кто вы.

Плеврайт может управлять только Chrome и Edge, а Arc всё вообще нельзя автоматизировать — поэтому окно входа всегда работает в Chrome/Edge и никогда в вашем браузере по умолчанию (остаётся нетронутым). Только если ни Chrome, ни Edge не установлены, login открывает Grafana в вашем браузере по умолчанию и пошагово проводит вас через копирование cookie grafana_session из DevTools один раз; при этом путь также попросит выйти из вкладки после этого, чтобы она не конкурировала за ротации сессии.

С этого момента сервер сам поддерживает сессию: Grafana отвечает на устаревшую сессию через 401 session.token.required, сервер вызывает POST /api/user/auth-tokens/rotate, атомарно сохраняет новую cookie и повторяет запрос. Поэтому сессия длится столько, сколько действует вход Grafana (по умолчанию 30 дней, 7 дней бездействия) — повторно выполните login в случаях, когда health сообщает failingLayer: "grafana".

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

Почему вставленная cookie обычно умирает через несколько минут

Grafana ≥ 10 ротирует токен сессии каждые несколько минут, и новый получает только один клиент. Если вы скопируете grafana_session из DevTools, пока вкладка остаётся открытой, браузер первую ротирует её, и копия в течение минут перестаёт действовать — это классический синдром «cookie перестала работать». login избегает этого, забирая сессию из браузера; login --paste также действует, если вы затем выйдете (или очистите cookie) в вкладке, из которой копировали, потому что сервер сохраняет свои ротации.

Grafana: другие учётные данные

scripts/verify.sh проверяет оба слоя и сообщает, что может видеть учётное — не выводя само значение.

Cloudflare Access (опционально)

Если Grafana находится за Cloudflare Zero Trust, каждый запрос также требует заголосов cf-access-token, либо edge перенаправит его на страницу входа до того, как Grafana увидет вызов. Сервер обрабатывает это автоматически:

1. Считывает закешированный JWT из ~/.cloudflared/<hostname>-<audience>-token (записанный через cloudflared access login);

2. Если отсутствует или истёк, запускает cloudflared access token --app=<GRAFANA_URL> (неинтерактивно);

3. Использует cookie CF_Authorization, захваченную командой login (если не истекла);

4. Взвращает к запасному CF_ACCESS_TOKEN;

5. При 302, если edge вернет закешированный токени и повторит один раз с новым.

Tokени разъяснится лениво, для качдору — никогда не один раз при запуске — поэтому истекающий токен самовосстанавливается вместо того, чтобы качдый Чouser вадался осшибкой до перезапуска клиента. Установка cloudflared опциональна, но рекомендована: его токен обновляется сам, любой до тех пор, пока ваш вход в Cloudflare не lawfulness gone, тогда как cookie, захваченная login, истекает сроком действия policy (usually 24h) и требует повторого login.

brew install cloudflared            # macOS; see Cloudflare's docs for Linux
cloudflared access login https://grafana.example.com

Cloudflare не за логар за вас. Х фирmэй.

Cloudflare не за логар за вас в Grafana. CF JWT доказывает, что вам разрешено обращение к хосту; после этого Grafana требует своей учётной записи. Ответ 302 / HTML — это Cloudflare; ответ JSON 401 — это Grafana. health сообщает, кто такой.

Не за Cloudflare? Установите GRAFANA_CF_ACCESS=off, либо просто не ставьте cloudflared — сервер пропускает уровень, если токен не можно найдите.

Структура проекта

src/
  main.ts                        # Entry point — `login` / `logout` commands, or the stdio MCP server
  login.ts                       # Browser sign-in (Playwright over your default Chromium-based browser) → session store
  default-browser.ts             # Detect the default browser (macOS LaunchServices / xdg) and whether it can be driven
  session-store.ts               # ~/.grafana-mcp/sessions/<host>.json, 0600, atomic writes
  grafana-client.ts              # Grafana HTTP client: two auth layers, CF retry, session rotation, datasource cache
  auth.ts                        # Grafana credential resolution (token / basic / session / file / login store)
  cf-token.ts                    # Cloudflare Access token: cache → cloudflared → login cookie → env, lazy + retry
  query-model.ts                 # Per-plugin /api/ds/query bodies (ClickHouse, SQL, PromQL/LogQL)
  allowed-datasources.ts         # Datasource allowlist
  utils/
    frames.ts                    # Data frames → rows
    format-response.ts           # Truncation, error results
  tools/
    list-datasources.tool.ts     # list_datasources
    query-sql.tool.ts            # query_sql
    query-metrics.tool.ts        # query_metrics
    search-dashboards.tool.ts    # search_dashboards
    get-dashboard.tool.ts        # get_dashboard
    health.tool.ts               # health
scripts/
  verify.sh                      # Check both auth layers; list what the credential can see
  mint-token.sh                  # Turn a fresh admin browser session into a service-account token

License

MIT