prometheus-mcp

PyPI version Python versions License: MIT Tests

MCP-сервер для метрик и наблюдаемости Prometheus. Предоставьте Claude (или любому агенту с поддержкой MCP) доступ на чтение к вашему экземпляру Prometheus — запрашивайте метрики с помощью PromQL, проверяйте активные алерты и изучайте цели сбора данных — не покидая чат.

Почему именно этот Prometheus MCP?

Существующие интеграции с Prometheus требуют написания пользовательских скриптов или глубокого знания API. Этот сервер:

Работает по стандартному протоколу Model Context Protocol через stdio — совместим с Claude Desktop, Claude Code, Cursor и любым другим MCP-клиентом.
Работает только на чтение: все 5 инструментов имеют флаг readOnlyHint: true — риск изменения данных в Prometheus отсутствует.
Возвращает двухканальный вывод: структурированный JSON (structuredContent) для программной обработки + Markdown (content) для удобного чтения человеком.
Содержит понятные сообщения об ошибках, которые указывают, какую переменную окружения нужно исправить, и предлагают дальнейшие шаги.
Поддерживает Bearer-токен, HTTP Basic auth или отсутствие авторизации (обычно для внутренних развертываний).

Инструменты

Инструмент	Эндпоинт	Описание
`prometheus_list_metrics`	`GET /api/v1/label/__name__/values`	Список всех имен метрик с опциональным фильтром по подстроке (лимит 500)
`prometheus_query`	`GET /api/v1/query`	Выполнение мгновенного PromQL-запроса
`prometheus_query_range`	`GET /api/v1/query_range`	Выполнение PromQL-запроса за диапазон времени с возвратом временных рядов
`prometheus_list_alerts`	`GET /api/v1/alerts`	Список активных и ожидающих алертов
`prometheus_list_targets`	`GET /api/v1/targets`	Список целей сбора данных (scrape targets) по состоянию и задаче

Установка

pip install prometheus-mcp

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

uvx prometheus-mcp

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

Вся настройка осуществляется через переменные окружения:

Переменная	Обязательно	По умолчанию	Описание
`PROMETHEUS_URL`	Да	—	URL сервера Prometheus, например `https://prometheus.example.com` (без слеша в конце)
`PROMETHEUS_TOKEN`	Нет	—	Bearer-токен (имеет приоритет над Basic auth)
`PROMETHEUS_USERNAME`	Нет	—	Имя пользователя для HTTP Basic auth
`PROMETHEUS_PASSWORD`	Нет	—	Пароль для HTTP Basic auth
`PROMETHEUS_SSL_VERIFY`	Нет	`true`	Установите `false` для самоподписанных сертификатов

Скопируйте .env.example в .env и заполните своими значениями.

Настройка Claude Desktop / Claude Code

Добавьте в конфигурацию MCP (claude_desktop_config.json или .claude/mcp.json):

{
  "mcpServers": {
    "prometheus": {
      "command": "prometheus-mcp",
      "env": {
        "PROMETHEUS_URL": "https://prometheus.example.com",
        "PROMETHEUS_TOKEN": "your-token-here"
      }
    }
  }
}

Или с помощью uvx (установка не требуется):

{
  "mcpServers": {
    "prometheus": {
      "command": "uvx",
      "args": ["prometheus-mcp"],
      "env": {
        "PROMETHEUS_URL": "https://prometheus.example.com"
      }
    }
  }
}

Docker

docker run --rm -e PROMETHEUS_URL=https://prometheus.example.com prometheus-mcp

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

После настройки спросите у Claude:

"Какие метрики есть в Prometheus по HTTP-запросам?"
"Какова текущая частота запросов для платежного сервиса?"
"Покажи использование CPU за последний час с разрешением 5 минут"
"Есть ли активные алерты? Какова их серьезность?"
"Какие цели сбора данных сейчас недоступны и почему?"
"Сколько экземпляров node-exporter сейчас работают?"

Руководство по использованию инструментов

`prometheus_list_metrics`

Возвращает все имена метрик, известные Prometheus. Используйте pattern для фильтрации по подстроке (регистронезависимо). Начните отсюда, если не знаете, какие метрики доступны. Вывод ограничен 500 метриками с уведомлением об усечении.

`prometheus_query`

Выполняет мгновенное выражение PromQL и получает текущие значения. Возвращает тип результата (vector/scalar/matrix/string), количество выборок, а также метки и значения для каждой выборки.

Параметры:

query (обязательно) — выражение PromQL, например up, rate(http_requests_total[5m])
time (опционально) — RFC3339 или Unix-таймстемп; по умолчанию — текущее время

`prometheus_query_range`

Выполняет выражение PromQL за временной интервал. Возвращает по одному ряду для каждого соответствующего временного ряда с данными, привязанными ко времени. Общее количество точек данных по всем рядам ограничено 5000.

Параметры:

query (обязательно) — выражение PromQL
start / end (обязательно) — RFC3339 или Unix-таймстемпы
step (обязательно) — разрешение, например 15s, 1m, 5m

Prometheus отклоняет шаги, которые привели бы к созданию > 11 000 точек на ряд (HTTP 422). Увеличьте шаг или сузьте диапазон, если это произойдет.

Примечание: API диапазонов Prometheus не поддерживает фильтрацию по ветке или коммиту — фильтры выражаются исключительно через сопоставление меток PromQL.

`prometheus_list_alerts`

Возвращает все активные/ожидающие алерты с метками (включая alertname, severity), состоянием, временем активации и текущим значением. Включает сводку состояний (количество срабатывающих против ожидающих).

`prometheus_list_targets`

Возвращает цели сбора данных с именем задачи, адресом экземпляра, состоянием здоровья (up/down/unknown), длительностью последнего сбора в миллисекундах и любым сообщением об ошибке. Включает сводку по каждой задаче. Фильтрация по state: active (по умолчанию), dropped или any.

Характеристики производительности

Все инструменты используют единую постоянную сессию requests.Session с пулом соединений.
Сессия имеет trust_env = False для обхода прокси-серверов окружения (Prometheus обычно является внутренней службой).
Запросы имеют таймаут 30 секунд.
prometheus_query_range ограничивает вывод 5000 общих точек по всем рядам — используйте больший шаг для длинных интервалов.
prometheus_list_metrics возвращает до 500 метрик после фильтрации.

Разработка

git clone https://github.com/mshegolev/prometheus-mcp
cd prometheus-mcp
pip install -e '.[dev]'
pytest tests/ -v
ruff check src tests
ruff format src tests

Лицензия

MIT — см. LICENSE.

mshegolev/prometheus-mcp