Prometheus MCP Server

Servidor MCP de Prometheus

Acerca de

Este es un servidor MCP que permite a los LLMs interactuar con una instancia de Prometheus en ejecución a través de la API para realizar tareas como generar y ejecutar consultas promql, listar y analizar métricas, etc.

Demostraciones y Ejemplos

Pidiendo a Claude que Investigue Consultas Lentas

El prompt utilizado fue:

consultar mis métricas es lento, ¿puedes ayudarme a averiguar por qué?

Investigar métricas producidas por el propio servidor MCP y sugerir reglas de grabación para SLOs

El prompt utilizado fue:

usa las herramientas del servidor mcp de prometheus para investigar las métricas del servidor mcp y sugiere reglas de grabación de prometheus para SLOs

Resumir las mejores prácticas de nomenclatura de métricas/etiquetas de Prometheus

El prompt utilizado fue:

resume las mejores prácticas de nombres de métricas/etiquetas de prometheus

Informe sobre la salud de la instancia de Prometheus que alimenta prometheus.demo.prometheus.io

El prompt utilizado fue:

por favor proporciona una revisión y resumen exhaustivos del servidor de prometheus. revisa su configuración, flags, información de runtime/build, y cualquier otra cosa que consideres que pueda proporcionar información sobre el estado de la instancia de prometheus, incluyendo el análisis de métricas y la ejecución de consultas

Herramientas

La API HTTP de Prometheus produce datos JSON, y las herramientas de este servidor MCP devuelven ese JSON al LLM para su procesamiento, ya que está estructurado y es bien comprendido por los LLMs.

LLMs y Eficiencia de Tokens/Contexto

Este servidor MCP admite las siguientes opciones que tienen el potencial de reducir el uso de tokens/contexto:

Codificación TOON

Si el uso de tokens/contexto es una preocupación, este servidor MCP también admite la conversión de los datos JSON de la API al formato Token-Oriented Object Notation (TOON). Aunque no se garantiza que reduzca el uso de tokens, está diseñado pensando en la eficiencia de tokens. Como se señala en la documentación de TOON, sobresale en arreglos uniformes de objetos; los objetos no uniformes/complejos pueden seguir siendo más eficientes en tokens en JSON. El uso de tokens en el mundo real dependerá de los patrones de uso; por favor revisa los flujos de trabajo comunes para determinar si la salida TOON puede ser beneficiosa. Consulta Flags para más información sobre los flags disponibles y sus variables de entorno correspondientes.

Truncamiento de Respuestas de la API

Esta característica permite establecer un límite máximo en el número de líneas o entradas devueltas por la API de Prometheus, lo que puede ayudar a reducir la cantidad de datos enviados al LLM. Establecer el límite en 0 desactiva el truncamiento. El truncamiento está desactivado por defecto. Ten en cuenta que los LLMs capaces de manejar argumentos de solicitudes de herramientas pueden anular este límite global de truncamiento por llamada de herramienta para las herramientas compatibles. Consulta Flags para más información sobre los flags disponibles y sus variables de entorno correspondientes.

Lista Completa de Herramientas

NOTA:

Debido a que los endpoints de la API de administración de TSDB permiten operaciones potencialmente destructivas como eliminar datos, no están habilitados por defecto. Para habilitar los endpoints de la API de administración de TSDB, el servidor MCP debe iniciarse con el flag --dangerous.enable-tsdb-admin-tools para reconocer el riesgo asociado que conllevan estos endpoints.

Conjuntos de Herramientas

El servidor expone muchas herramientas para interactuar con Prometheus. Hay herramientas para interactuar con Prometheus a través de la API, así como herramientas adicionales para hacer cosas como leer documentación, etc. Por defecto, todas están registradas y disponibles para su uso (las herramientas de la API de administración de TSDB necesitan un flag adicional).

Para ser considerado con los LLMs con ventanas de contexto más pequeñas, es posible pasar una lista blanca de herramientas específicas para registrar con el servidor. Las siguientes herramientas 'principales' siempre se cargan: [docs_list, docs_read, docs_search, runbooks_list, runbooks_read, query, range_query, metric_metadata, label_names, label_values, series]. Se pueden especificar herramientas adicionales con el flag --mcp.tools.

Por ejemplo, la línea de comandos:

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

Resultaría en la carga de las siguientes herramientas:

• 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

Runbooks (Agent Skills) y Prompts

El servidor incrusta un conjunto de runbooks: flujos de trabajo guiados para tareas comunes de Prometheus, expresados en términos de las herramientas del servidor. Cada runbook orienta al modelo sobre las herramientas relevantes, luego sugiere temas para explorar con consultas de ejemplo en lugar de prescribir una secuencia fija de pasos. Los runbooks cubren tareas como verificaciones de salud del sistema, triaje de datos faltantes, investigación de tasas de error, optimización de alta cardinalidad, revisión de reglas de grabación/alertas, y ajuste de configuración/rendimiento.

Cada runbook está empaquetado como un Agent Skill completo: un directorio que contiene un SKILL.md con frontmatter name/description. Los runbooks se exponen de tres maneras:

• Herramientas: el modelo puede descubrirlos y leerlos por sí mismo a través de las herramientas runbooks_list/runbooks_read cuando una solicitud coincide con el propósito de un runbook. Las herramientas son la vía más portátil y funcionan en todos los clientes MCP.
• Recursos de skills: según el borrador de extensión de skills SEP-2640, cada runbook es un recurso skill://<name>/SKILL.md, enumerado por el índice de descubrimiento bien conocido skill://index.json, y el servidor declara la capacidad de extensión io.modelcontextprotocol/skills. Los hosts que reconocen skills pueden consumirlos como skills del sistema de archivos local; otros clientes aún pueden leerlos como recursos MCP ordinarios.
• Prompts MCP: cada runbook también está registrado como un prompt MCP bajo su nombre de skill (por ejemplo, check-system-health, optimize-high-cardinality), por lo que los clientes con soporte de prompts pueden invocar un flujo de trabajo guiado directamente (a menudo presentado como comandos de barra).

Backends Compatibles con Prometheus

Hay muchos backends compatibles con Prometheus que se pueden usar para extender prometheus de diversas maneras, a menudo con los objetivos de ofrecer almacenamiento a largo plazo o agregación de consultas desde múltiples instancias de prometheus. Algunos ejemplos se pueden encontrar en el Remote Storage de la documentación de prometheus.

Muchos de esos servicios también ofrecen una API "compatible con prometheus" que se puede usar para consultar/interactuar con los datos usando promQL nativo. En general, este servidor MCP debería funcionar como mínimo para otros servicios compatibles con la API de prometheus para ejecutar consultas e interactuar con los endpoints de series/etiquetas/metadatos para el descubrimiento de métricas y etiquetas. Más allá de eso, puede haber diferencias en la API ya que los diferentes sistemas implementan diferentes partes/extensiones de la API según sus necesidades.

Ejemplos:

• Thanos no usa una configuración centralizada, por lo que el endpoint de configuración no está implementado y, por lo tanto, la herramienta de configuración falla.
• Mimir y Cortex implementan endpoints adicionales para gestionar/añadir/eliminar reglas.

Para solucionar esto y proporcionar una mejor experiencia en algunos de los sistemas compatibles con Prometheus más utilizados, este proyecto puede agregar soporte directo para sistemas seleccionados para proporcionar herramientas diferentes/más. Elegir una implementación de backend de prometheus específica se puede hacer con el flag --prometheus.backend. La lista de implementaciones de backend disponibles en una versión dada del servidor MCP se puede encontrar en la salida del flag --help. Las calificaciones y criterios de soporte aún están bajo consideración; por favor abre un issue para solicitar soporte/características para un backend específico para una discusión adicional.

Diferencias de Implementación del Backend de Prometheus

Recursos

Instalación y uso

Este servidor MCP es más útil cuando está completamente integrado con herramientas y/o instalado como un servidor de herramientas con otro sistema. Los procedimientos de instalación y el soporte de integración variarán según las herramientas utilizadas. Por ejemplo:

• algunos sistemas solo pueden interactuar con herramientas MCP y no con recursos/indicaciones
• algunos sistemas usan el formato de archivo de configuración mcp.json para gestionar servidores MCP y algunos requieren formatos personalizados
• algunos sistemas no hablan MCP directamente y requieren herramientas como mcp-to-openapi para proxy

Consulte la documentación de la herramienta utilizada/integrada para obtener instrucciones específicas y el nivel de soporte.

Binario

Descargue una versión adecuada para su sistema desde la página de Lanzamientos. Consulte Banderas para obtener más información sobre las banderas disponibles y sus variables de entorno correspondientes.

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

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

Docker

Consulte Banderas para obtener más información sobre las banderas disponibles y sus variables de entorno correspondientes.

# 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

Gráfico Helm (Kubernetes)

Hay un gráfico Helm disponible para implementar en Kubernetes. El gráfico se publica como un artefacto OCI en cada lanzamiento.

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

Consulte el README del gráfico para obtener la lista completa de valores de configuración y ejemplos.

Kubernetes (Manifiestos sin procesar)

Si prefiere implementar sin Helm, hay manifiestos de Kubernetes de ejemplo disponibles:

• Implementación de Kubernetes
• Implementación de OpenShift

Paquetes del sistema

Descargue una versión adecuada para su sistema desde la página de Lanzamientos. Se incluye un archivo de servicio Systemd en los paquetes del sistema que se compilan.

# 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

Nota: Aunque los paquetes se compilan para varios sistemas, actualmente no hay planes para intentar enviar paquetes a los repositorios de paquetes ascendentes.

Seguridad y autenticación

Conexión a instancias seguras de Prometheus

El servidor MCP admite archivos de configuración HTTP de Prometheus para conectarse a instancias seguras de Prometheus. Se puede encontrar un ejemplo de configuración en la carpeta de ejemplos aquí. Use la bandera de línea de comandos --http.config para proporcionar un archivo de configuración HTTP. Consulte Banderas para obtener más información.

Reenvío de credenciales del cliente

Al usar el transporte HTTP, el servidor MCP reenvía el encabezado Authorization en cada solicitud MCP a Prometheus para las llamadas API de esa solicitud. Las solicitudes que no llevan un encabezado Authorization, y todas las solicitudes a través del transporte stdio, usan el cliente predeterminado construido a partir de banderas (consulte Conexión a instancias seguras de Prometheus).

El servidor reenvía las credenciales del cliente a Prometheus tal como están y no las valida. Una credencial que no incluye un esquema de autenticación se envía como un token Bearer. Cualquier persona que pueda alcanzar el endpoint MCP puede consultar Prometheus con al menos las credenciales del cliente predeterminado, por lo que restrinja el acceso al endpoint con un archivo de configuración web o controles a nivel de red. Tenga en cuenta que la autenticación básica en el archivo de configuración web (basic_auth_users) entra en conflicto con el reenvío de credenciales: el mismo encabezado Authorization que un cliente usa para autenticarse en el servidor MCP se reenvía a Prometheus en lugar de las credenciales del cliente predeterminado. Las configuraciones web solo TLS no usan el encabezado Authorization y no se ven afectadas.

Asegurar los endpoints del servidor MCP

El servidor MCP admite archivos de configuración web de Prometheus para exponer sus endpoints detrás de autenticación básica opcional y configuraciones TLS personalizadas. Use la bandera de línea de comandos --web.config.file para proporcionar un archivo de configuración HTTP. Consulte Banderas para obtener más información.

Telemetría

Endpoints de salud

El servidor web expone endpoints de salud en la dirección de escucha configurada, siguiendo la convención /-/healthy y /-/ready utilizada en todo el ecosistema de Prometheus:

Estos se asignan directamente a las sondas de liveness/readiness de Kubernetes. La métrica prom_mcp_server_ready informa el mismo estado de readiness.

Métricas

Una vez en ejecución, el servidor expone métricas de Prometheus en la dirección de escucha y la ruta de telemetría configuradas (:8080/metrics, por defecto). Consulte Banderas para obtener más información sobre cómo cambiar la interfaz de escucha, el puerto o la ruta de telemetría.

Panel de Grafana

Se incluye un panel de Grafana preconstruido en el directorio grafana/ para visualizar las métricas expuestas por el servidor MCP. Importe el json del panel en grafana y debería estar listo para usar.

Registros

Este proyecto hace un uso intensivo de registros estructurados y con niveles. Consulte Banderas para obtener más información sobre cómo configurar el formato de registro, el nivel y el archivo opcional.

Desarrollo

Entorno de desarrollo con Devbox + Direnv

Si usa Devbox y Direnv, simplemente entrar al directorio del repositorio debería configurar el software necesario.

LLM local con Ollama

Consulte mcp.json para ver un ejemplo de configuración MCP para usar con herramientas. Requiere que ollama esté instalado.

NOTA:

Para anular el LLM predeterminado (ollama:gpt-oss:20b), ejecute export OLLAMA_MODEL="ollama:your_model" to override it before running make .

make inspector

make mcphost

Gemini con gemini-cli

Consulte settings.json para ver un ejemplo de archivo de configuración para ejecutar gemini-cli con prometheus-mcp-server. Requiere que gemini-cli esté instalado.

make gemini

Configuración manual

Software requerido:

• Entorno Go funcional
• Docker para pruebas locales/linting/construcción de imágenes/etc
• GNU Make
• ollama
• mcp inspector
• mcphost

Construcción

Este proyecto utiliza el conjunto de herramientas de construcción estándar de Prometheus: promu impulsado a través de Makefile / Makefile.common. El binario incrusta una instantánea fijada de prometheus/docs, que los objetivos de construcción descargan y extraen automáticamente (la fijación vive en DOCS_VERSION en el 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

Los objetivos auxiliares específicos del proyecto (empaquetado de helm e integraciones de clientes LLM locales) se enumeran mediante 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

Banderas de línea de comandos

Las banderas de línea de comandos disponibles están documentadas en la bandera de ayuda:

~/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)