prometheus-mcp

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 или отсутствие авторизации (обычно для внутренних развертываний).

Related MCP server: Prometheus MCP Server

Инструменты

Установка

pip install prometheus-mcp

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

uvx prometheus-mcp

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

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

Скопируйте .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.