Сервер Prometheus MCP

О программе

Это MCP сервер, который позволяет LLM взаимодействовать с запущенным экземпляром Prometheus через API для выполнения задач, таких как генерация и выполнение запросов PromQL, просмотр и анализ метрик и т. д.

Демонстрации и примеры

Просьба к Claude расследовать медленные запросы

Используемый запрос:

запросы к моим метрикам медленные, можешь помочь мне понять почему?

Анализ метрик, производимых самим сервером MCP, и рекомендация правил записи для SLO

Используемый запрос:

используй инструменты сервера prometheus mcp для анализа метрик сервера mcp и предложи правила записи prometheus для SLO

Сводка рекомендаций по именованию метрик/меток Prometheus

Используемый запрос:

сведи в сводку рекомендации по именованию метрик/меток Prometheus

Отчёт о состоянии сервера Prometheus, который поддерживает prometheus.demo.prometheus.io

Используемый запрос:

предоставь подробный обзор и сводку сервера Prometheus. проанализируй его конфигурацию, флаги, информацию о среде выполнения/сборке, и любую другую информацию, которая может дать понять о состоянии экземпляра Prometheus, включая анализ метрик и выполнение запросов

Инструменты

HTTP API Prometheus возвращает данные в формате JSON, и инструменты этого сервера MCP передают этот JSON LLM для обработки, так как структура данных понятна и привычна для LLM.

LLM и эффективность использования токенов/контекста

Этот сервер MCP поддерживает следующие параметры, которые могут снизить использование токенов/контекста:

Кодировка TOON

Если использование токенов/контекста является проблемой, этот сервер MCP также поддерживает преобразование данных JSON API в формат Token-Oriented Object Notation (TOON). Хотя гарантировать снижение использования токенов нельзя, формат разработан с учётом эффективности токенов. Как отмечено в документации TOON, он отлично справляется с однородными массивами объектов; неоднородные/сложные объекты всё ещё могут быть более эффективны в JSON. Фактическое использование токенов зависит от сценариев использования. Рекомендуется изучить типичные рабочие процессы, чтобы определить, действительно ли вывод в формате TOON может принести пользу. Дополнительные сведения о доступных флагах и соответствующих переменных окружения см. в разделе Флаги командной строки.

Усечение ответов API

Эта функция позволяет установить максимальное количество строк или записей, возвращаемых из API Prometheus, что может помочь сократить объём данных, отправляемых LLM. Установка значения 0 отключает усечение. По умолчанию усечение отключено.

Флаги командной строки

prometheus-mcp-server --mcp.tools=build_info --mcp.tools=flags --mcp.tools=runtime_info

Переменные окружения

Сборка

/path/to/prometheus-mcp-server <flags>

# or using env vars
PROMETHEUS_MCP_SERVER_PROMETHEUS_URL="https://$yourPrometheus:9090" /path/to/prometheus-mcp-server

Использование

# Stdio transport
docker run --rm -i ghcr.io/tjhop/prometheus-mcp-server:latest --prometheus.url "https://$yourPrometheus:9090" 

# or using env vars
docker run --rm -i -e PROMETHEUS_MCP_SERVER_PROMETHEUS_URL="https://$yourPrometheus:9090" ghcr.io/tjhop/prometheus-mcp-server:latest

Монтринг

Этот сервер MCP предоставляет собой метрики Prometheus о самом себе, включая:

• Количество вызванных инструментов
• Количество запросов к API Prometheus, включая количество ошибок
• Общее время выполнения запросов к API Prometheus
• Размер ответов API Prometheus

Эти метрики доступны на стандартном эндпоинте метрик Prometheus (/metrics) по адресу, указанному в параметре --address.

Лицензия

Проект распространяется по лицензии MIT. Подробности см. в файле LICENSE. Обратите внимание, что LLM, способные обрабатывать аргументы вызова инструментов, могут переопределять это глобальное ограничение на усечение для каждого вызова инструмента индивидуально (для поддерживаемых инструментов). Пожалуйста, ознакомьтесь с разделом Флаги для получения информации о доступных флагах и соответствующих переменных окружения.

Полный список инструментов

ПРИМЕЧАНИЕ:

Поскольку эндпоинты администрирования TSDB позволяют выполнять потенциально разрушительные операции, такие как удаление данных, они не включены по умолчанию. Чтобы включить эндпоинты администрирования TSDB, сервер MCP должен быть запущен с флагом --dangerous.enable-tsdb-admin-tools для подтверждения связанного с этими эндпоинтами риска.

Наборы инструментов

Сервер предоставляет множество инструментов для взаимодействия с Prometheus. Существуют инструменты для взаимодействия с Prometheus через API, а также дополнительные инструменты для выполнения задач, таких как чтение документации и т.д. По умолчанию все они зарегистрированы и доступны для использования (инструменты TSDB Admin API требуют дополнительного флага).

Чтобы быть внимательными к LLM с меньшей ёмкостью контекста, можно передать белый список конкретных инструментов для регистрации с сервером. Следующие 'основные' инструменты всегда загружаются: [docs_list, docs_read, docs_search, runbooks_list, runbooks_read, query, range_query, metric_metadata, label_names, label_values, series]. Дополнительные инструменты можно указать с помощью флага --mcp.tools.

Например, команда:

prometheus-mcp-server --mcp.tools=build_info --mcp.tools=flags --mcp.tools=runtime_info

приведет к загрузке следующих инструментов:

• build_info
• docs_list
• docs_read
• docs_search
• flags
• label_names
• label_values
• metric_metadata
• query
• range_query
• runbooks_list
• runbooks_read
• runtime_info
• series

Руководства (Навыки агентов) и запросы

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

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

Каждое руководство упаковано как полный Agent Skill: каталог, содержащий SKILL.md с метаданными name/description. Руководства доступны тремя способами:

• Инструменты: модель может сама обнаружить и прочитать их через инструменты runbooks_list/runbooks_read, когда запрос соответствует цели руководства. Инструменты — самый переносимый путь и работают во всех клиентах MCP.
• Ресурсы навыков: согласно черновику расширения навыков SEP-2640, каждое руководство является ресурсом skill://<name>/SKILL.md, перечисляемым в известном индексе обнаружения skill://index.json, и сервер объявляет расширение io.modelcontextprotocol/skills. Хосты, поддерживающие навыки, могут использовать их как локальные навыки файловой системы; другие клиенты всё ещё могут прочитать их как обычные ресурсы MCP.
• Запросы MCP: каждое руководство также зарегистрировано как запрос MCP под именем своего навыка (например, check-system-health, optimize-high-cardinality), чтобы клиенты с поддержкой запросов могли напрямую вызвать пошаговый рабочий процесс (часто отображаемый как команды со слешем).

Совместимые с Prometheus бэкенды

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

Некоторые примеры можно найти в разделе Удалённое хранилище документации Prometheus.

Многие из этих сервисов также предоставляют API, совместимое с Prometheus, которое можно использовать для выполнения запросов и взаимодействия с данными с использованием нативного PromQL.

В целом, этот сервер MCP должен по крайней мере поддерживать работу с другими сервисами, совместимыми с API Prometheus, для выполнения запросов и взаимодействия с конечными точками серии/метки/метаданных для обнаружения метрик и меток.

Помимо этого, могут существовать различия в API, поскольку разные системы реализуют разные части или расширения API по своим нуждам.

Примеры: - Thanos не использует централизованную конфигурацию, поэтому конечная точка конфигурации не реализована, и инструмент конфигурации завершается ошибкой. - Mimir и Cortex реализуют дополнительные конечные точки для управления/добавления/удаления правил

Чтобы обойти это и обеспечить лучший опыт на некоторых часто используемых совместимых с Prometheus системах, этот проект может добавить прямую поддержку выборочных систем для предоставления разных/дополнительных инструментов.

Выбор конкретной реализации бэкенда Prometheus можно выполнить с помощью флага --prometheus.backend.

Список доступных реализаций бэкендов в определённом выпуске сервера MCP можно найти в выводе флага --help.

Квалификации и критерии поддержки всё ещё находятся на рассмотрении, пожалуйста, создайте задачу, чтобы запросить поддержку/функции для конкретного бэкенда для дальнейшего обсуждения.

Различия в реализации бэкенда Prometheus

Installation and Usage

Этот сервер MCP наиболее полезен, когда полностью интегрирован с инструментами и/или установлен как сервер инструментов вместе с другой системой. Процедуры установки и поддержка интеграции будут варьироваться в зависимости от используемых инструментов. Например: - некоторые системы могут взаимодействовать только с инструментами MCP, но не с ресурсами/пROMPTами - некоторые системы используют файл конфигурации mcp.json для управления серверами MCP, а некоторые требуют специальных форматов - некоторые системы не поддерживают MCP напрямую и требуют инструменты, такие как mcp-to-openapi для проксирования

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

Binary

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

/path/to/prometheus-mcp-server <flags>

# or using env vars
PROMETHEUS_MCP_SERVER_PROMETHEUS_URL="https://$yourPrometheus:9090" /path/to/prometheus-mcp-server

Docker

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

# Stdio transport
docker run --rm -i ghcr.io/tjhop/prometheus-mcp-server:latest --prometheus.url "https://$yourPrometheus:9090" 

# or using env vars
docker run --rm -i -e PROMETHEUS_MCP_SERVER_PROMETHEUS_URL="https://$yourPrometheus:9090" ghcr.io/tjhop/prometheus-mcp-server:latest

# Streamable HTTP transport (capable of SSE as well)
docker run --rm -p 8080:8080 ghcr.io/tjhop/prometheus-mcp-server:latest --prometheus.url "https://$yourPrometheus:9090" --mcp.transport "http" --web.listen-address ":8080"

# or using env vars
docker run --rm -p 8080:8080 -e PROMETHEUS_MCP_SERVER_PROMETHEUS_URL="https://$yourPrometheus:9090" -e PROMETHEUS_MCP_SERVER_MCP_TRANSPORT="http" -e PROMETHEUS_MCP_SERVER_WEB_LISTEN_ADDRESS=":8080" ghcr.io/tjhop/prometheus-mcp-server:latest

Helm Chart (Kubernetes)

Доступен Helm-чарт для развертывания в Kubernetes. Чарт публикуется как артефакт OCI при каждом выпуске.

helm install prometheus-mcp-server oci://ghcr.io/tjhop/charts/prometheus-mcp-server \
  --version <version> \
  --set prometheus.url=http://prometheus:9090

См. chart README для получения полного списка значений конфигурации и примеров.

Kubernetes (Raw Manifests)

Если вы предпочитаете развертывание без Helm, доступны примеры манифестов Kubernetes:

• Kubernetes Deployment
• OpenShift Deployment

System Packages

Загрузите подходящий выпуск для вашей системы со страницы Releases. В системных пакетах включён файл службы Systemd.

# install system package (example assuming Debian based)
apt install /path/to/package
# create unit override, add any needed flags or environment variables
systemctl edit prometheus-mcp-server.service
systemctl enable --now prometheus-mcp-server.service

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

Security and Authentication

Connecting to Secure Prometheus Instances

Сервер MCP поддерживает Prometheus HTTP config файлы для подключения к защищённым экземплярам Prometheus. Пример конфигурации можно найти в папке примеров здесь. Используйте флаг --http.config командной строки, чтобы указать файл конфигурации HTTP. Пожалуйста, обратитесь к разделу Flags для получения дополнительной информации.

Forwarding Client Credentials

При использовании транспорта HTTP сервер MCP пересылает заголовок Authorization с каждого запроса MCP к Prometheus для API-вызовов этого запроса. Запросы, не содержащие заголовка Authorization, и все запросы по транспорту stdio используют клиента по умолчанию, созданного с помощью флагов (см. Connecting to Secure Prometheus Instances).

Сервер пересылает учётные данные клиента в Prometheus без изменений и не проверяет их. Учётные данные без схемы аутентификации отправляются как токен Bearer. Любой, кто может получить доступ к конечной точке MCP, может выполнять запросы к Prometheus с использованием по крайней мере учётных данных клиента по умолчанию, поэтому ограничьте доступ к конечной точке с помощью файла конфигурации веб-интерфейса или сетевых уровней контроля. Обратите внимание, что базовая аутентификация в файле конфигурации веб-интерфейса (basic_auth_users) конфликтует с пересылкой учётных данных: тот же заголовок Authorization, который клиент использует для аутентификации на сервере MCP, затем пересылается в Prometheus вместо учётных данных клиента по умолчанию. TLS-only web configurations do not use the Authorization header and are unaffected.

Securing the MCP Server Endpoints

The MCP server supports Prometheus Web Configuration files files to expose it's endpoints behind optional basic auth and custom TLS configs. Use the --web.config.file command-line flag to provide an HTTP configuration file. Please see Flags for more information.

Telemetry

Health Endpoints

The web server exposes health endpoints on the configured listen address, following the /-/healthy and /-/ready convention used across the Prometheus ecosystem:

These map directly onto Kubernetes liveness/readiness probes. The prom_mcp_server_ready metric reports the same readiness state.

Metrics

Once running, the server exposes Prometheus metrics on the configured listen address and telemetry path (:8080/metrics, by default). Please see Flags for more information on how to change the listening interface, port, or telemetry path.

Prometheus MCP Server Metrics

Grafana Dashboard

A pre-built Grafana dashboard is included in the grafana/ directory for visualizing the metrics exposed by the MCP server. Import the dashboard json into grafana and it should be ready to go.

Logs

This project makes heavy use of structured, leveled logging. Please see Flags for more information on how to set the log format, level, and optional file.

Development

Development Environment with Devbox + Direnv

If you use Devbox and Direnv, then simply entering the directory for the repo should set up the needed software.

Local LLM with Ollama

See mcp.json for an example MCP config for use with tooling. Requires ollama to be installed.

NOTE:

To override the default LLM (ollama:gpt-oss:20b), run export OLLAMA_MODEL="ollama:your_model" to override it before running make .

Using MCP Inspector and a local ollama instance:

Requires MCP Inpsector to be installed:

make inspector

Using mcphost and a local ollama instance:

Требуется установленный mcphost:

make mcphost

Gemini с gemini-cli

См. settings.json для примера конфигурационного файла для запуска gemini-cli с prometheus-mcp-server. Требуется установленный gemini-cli.

Использование gemini-cli с размещенными моделями:

make gemini

Ручная настройка

Необходимое программное обеспечение: - Рабочая среда Go - Docker для локальных тестов/линтинга/сборки образов и т.д. - GNU Make - ollama - mcp inspector - mcphost

Сборка

Этот проект использует стандартные средства сборки Prometheus: promu, управляемые через Makefile / Makefile.common. Двоичный файл встраивает закрепленную снимок prometheus/docs, которые целевые сборки загружают и извлекают автоматически (закрепление находится в DOCS_VERSION в Makefile).

make build       # build the binary for the host platform (via promu)
make test        # run the test suite
make crossbuild  # build binaries for all release platforms
make             # run the full check suite: style, license, yamllint, lint, build, test

Специфичные для проекта вспомогательные цели (упаковка helm и локальные клиентские интеграции LLM) перечислены командой make help:

make help

Usage:
  make <target>

Project targets:
  help                           print this help message (see Makefile.common for the standard prometheus targets)
  docs                           download and extract the pinned prometheus/docs snapshot for embedding
  helm-sync-dashboards           copy grafana dashboards into helm chart for packaging
  helm-lint                      run helm chart linting
  helm-template                  render helm templates for inspection
  helm-test                      install helm chart and run tests (requires a running cluster)
  mcphost                        use mcphost to run the prometheus-mcp-server against a local ollama model
  inspector                      use inspector to run the prometheus-mcp-server in STDIO transport mode
  inspector-http                 use inspector to run the prometheus-mcp-server in streamable HTTP transport mode
  open-webui                     use open-webui to run the prometheus-mcp-server
  gemini                         use gemini-cli to run the prometheus-mcp-server against Google Gemini models

Флаги командной строки

Доступные флаги командной строки документированы в справочном флаге:

~/go/src/github.com/tjhop/prometheus-mcp-server (main [ ]) -> ./prometheus-mcp-server --help
usage: prometheus-mcp-server [<flags>]


Flags:
  -h, --[no-]help                Show context-sensitive help (also
                                 try --help-long and --help-man).
                                 ($PROMETHEUS_MCP_SERVER_HELP)
      --mcp.tools=all ...        List of mcp tools to load. The target
                                 `all` can be used to load all tools.
                                 The target `core` loads only the core tools:
                                 docs_list,docs_read,docs_search,runbooks_list,runbooks_read,query,range_query,metric_metadata,label_names,label_values,series
                                 Otherwise, it is treated as an allow-list
                                 of tools to load, in addition to the core
                                 tools. Please see project README for more
                                 information and the full list of tools.
                                 ($PROMETHEUS_MCP_SERVER_MCP_TOOLS)
      --[no-]mcp.enable-toon-output  
                                 Enable Token-Oriented Object Notation
                                 (TOON) output for tools instead of JSON
                                 ($PROMETHEUS_MCP_SERVER_MCP_ENABLE_TOON_OUTPUT)
      --[no-]mcp.enable-client-logging  
                                 Enable sending log messages to connected
                                 MCP clients as protocol notifications.
                                 When enabled, tool execution logs are
                                 sent both to the server's primary
                                 log output and to the MCP client,
                                 allowing LLMs to observe server activity.
                                 ($PROMETHEUS_MCP_SERVER_MCP_ENABLE_CLIENT_LOGGING)
      --mcp.transport="stdio"    The type of transport to use for
                                 the MCP server [`stdio`, `http`].
                                 ($PROMETHEUS_MCP_SERVER_MCP_TRANSPORT)
      --prometheus.backend=PROMETHEUS.BACKEND  
                                 Customize the toolset for a specific
                                 Prometheus API compatible backend.
                                 Supported backends include: prometheus,thanos
                                 ($PROMETHEUS_MCP_SERVER_PROMETHEUS_BACKEND)
      --prometheus.url="http://127.0.0.1:9090"  
                                 URL of the Prometheus instance to connect to
                                 ($PROMETHEUS_MCP_SERVER_PROMETHEUS_URL)
      --prometheus.timeout=1m    Timeout for API calls to the Prometheus backend
                                 ($PROMETHEUS_MCP_SERVER_PROMETHEUS_TIMEOUT)
      --prometheus.truncation-limit=0  
                                 If enabled, this controls the maximum query
                                 response size in number of lines/entries
                                 provided to the LLM from the API response.
                                 LLMs can override truncation limits if
                                 needed on a per-tool-call basis via tool
                                 request arguments on supported tools.
                                 To disable truncation limits, set to 0.
                                 ($PROMETHEUS_MCP_SERVER_PROMETHEUS_TRUNCATION_LIMIT)
      --http.config=HTTP.CONFIG  Path to config file to set
                                 Prometheus HTTP client options
                                 ($PROMETHEUS_MCP_SERVER_HTTP_CONFIG)
      --web.telemetry-path="/metrics"  
                                 Path under which to expose metrics.
                                 ($PROMETHEUS_MCP_SERVER_WEB_TELEMETRY_PATH)
      --web.max-requests=40      Maximum number of parallel scrape
                                 requests. Use 0 to disable.
                                 ($PROMETHEUS_MCP_SERVER_WEB_MAX_REQUESTS)
      --[no-]dangerous.enable-tsdb-admin-tools  
                                 Enable and allow using tools that access
                                 Prometheus' TSDB Admin API endpoints
                                 (`snapshot`, `delete_series`, and
                                 `clean_tombstones` tools). This is dangerous,
                                 and allows for destructive operations
                                 like deleting data. It is not the fault
                                 of this MCP server if the LLM you're
                                 connected to nukes all your data. Docs:
                                 https://prometheus.io/docs/prometheus/latest/querying/api/#tsdb-admin-apis
                                 ($PROMETHEUS_MCP_SERVER_DANGEROUS_ENABLE_TSDB_ADMIN_TOOLS)
      --[no-]docs.auto-update    Enable automatic documentation updates
                                 from the official prometheus/docs
                                 repository. Checks every 24h0m0s.
                                 ($PROMETHEUS_MCP_SERVER_DOCS_AUTO_UPDATE)
      --log.file=LOG.FILE        The name of the file to log to (file
                                 rotation policies should be configured
                                 with external tools like logrotate)
                                 ($PROMETHEUS_MCP_SERVER_LOG_FILE)
      --[no-]web.systemd-socket  Use systemd socket activation listeners
                                 instead of port listeners (Linux only).
                                 ($PROMETHEUS_MCP_SERVER_WEB_SYSTEMD_SOCKET)
      --web.listen-address=:8080 ...  
                                 Addresses on which to expose metrics and
                                 web interface. Repeatable for multiple
                                 addresses. Examples: `:9100` or `[::1]:9100`
                                 for http, `vsock://:9100` for vsock
                                 ($PROMETHEUS_MCP_SERVER_WEB_LISTEN_ADDRESS)
      --web.config.file=""       Path to configuration file that can
                                 enable TLS or authentication. See:
                                 https://github.com/prometheus/exporter-toolkit/blob/master/docs/web-configuration.md
                                 ($PROMETHEUS_MCP_SERVER_WEB_CONFIG_FILE)
      --log.level=info           Only log messages with the given severity
                                 or above. One of: [debug, info, warn, error]
                                 ($PROMETHEUS_MCP_SERVER_LOG_LEVEL)
      --log.format=logfmt        Output format of log messages. One of: [logfmt,
                                 json] ($PROMETHEUS_MCP_SERVER_LOG_FORMAT)
      --[no-]version             Show application version.
                                 ($PROMETHEUS_MCP_SERVER_VERSION)