Prometheus MCP Server

Servidor MCP do Prometheus

Sobre

Este é um servidor MCP para permitir que LLMs interajam com uma instância Prometheus em execução por meio da API, para fazer coisas como gerar e executar consultas promql, listar e analisar métricas, etc.

Demonstrações e Exemplos

Pedindo ao Claude para Investigar Consultas Lentas

O prompt utilizado foi:

minhas métricas estão lentas, você pode me ajudar a descobrir o porquê?

Investigar métricas produzidas pelo próprio servidor MCP e sugerir regras de gravação para SLOs

O prompt utilizado foi:

use as ferramentas do servidor mcp do prometheus para investigar as métricas do servidor mcp e sugerir regras de gravação do prometheus para SLOs

Resumir as melhores práticas de nomenclatura de métricas/rótulos do Prometheus

O prompt utilizado foi:

resuma as melhores práticas de nomes de métricas/rótulos do prometheus

Relatório sobre a saúde da instância do Prometheus que alimenta prometheus.demo.prometheus.io

O prompt utilizado foi:

forneça uma revisão e resumo abrangentes do servidor prometheus. revise sua configuração, flags, informações de runtime/build e qualquer outra coisa que você considere que possa fornecer insights sobre o status da instância do prometheus, incluindo análise de métricas e execução de consultas

Ferramentas

A API HTTP do Prometheus gera dados em JSON, e as ferramentas deste servidor MCP retornam esse JSON ao LLM para processamento, pois é estruturado e bem compreendido por LLMs.

LLMs e Eficiência de Token/Contexto

Este servidor MCP suporta as seguintes opções que têm o potencial de reduzir o uso de token/contexto:

Codificação TOON

Se o uso de token/contexto for uma preocupação, este servidor MCP também suporta a conversão dos dados JSON da API para o formato Token-Oriented Object Notation (TOON). Embora não seja garantido reduzir o uso de tokens, ele é projetado com eficiência de tokens em mente. Conforme observado na documentação do TOON, ele se destaca em arrays uniformes de objetos; objetos não uniformes/complexos podem ainda ser mais eficientes em tokens no JSON. O uso real de tokens dependerá dos padrões de uso; revise os fluxos de trabalho comuns para determinar se a saída TOON pode ser benéfica. Consulte Flags para obter mais informações sobre as flags disponíveis e suas variáveis de ambiente correspondentes.

Truncamento de Resposta da API

Este recurso permite definir um limite máximo no número de linhas ou entradas retornadas pela API do Prometheus, o que pode ajudar a reduzir a quantidade de dados enviados ao LLM. Definir o limite como 0 desativa o truncamento. O truncamento é desativado por padrão. Observe que LLMs capazes de lidar com argumentos de solicitação de ferramentas podem substituir esse limite global de truncamento por chamada de ferramenta para ferramentas suportadas. Consulte Flags para obter mais informações sobre as flags disponíveis e suas variáveis de ambiente correspondentes.

Lista Completa de Ferramentas

NOTA:

Como os endpoints da API de administração do TSDB permitem operações potencialmente destrutivas, como exclusão de dados, eles não são habilitados por padrão. Para habilitar os endpoints da API de administração do TSDB, o servidor MCP deve ser iniciado com a flag --dangerous.enable-tsdb-admin-tools para reconhecer o risco associado que esses endpoints carregam.

Conjuntos de Ferramentas

O servidor expõe muitas ferramentas para interagir com o Prometheus. Há ferramentas para interagir com o Prometheus por meio da API, bem como ferramentas adicionais para fazer coisas como ler documentação, etc. Por padrão, todas são registradas e disponíveis para uso (as ferramentas da API de administração do TSDB precisam de uma flag extra).

Para ser atencioso com LLMs que possuem janelas de contexto menores, é possível passar uma lista de permissões de ferramentas específicas para registrar no servidor. As seguintes ferramentas 'principais' são sempre carregadas: [docs_list, docs_read, docs_search, runbooks_list, runbooks_read, query, range_query, metric_metadata, label_names, label_values, series]. Ferramentas adicionais podem ser especificadas com a flag --mcp.tools.

Por exemplo, a linha de comando:

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

Resultaria no carregamento das seguintes ferramentas:

• 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) e Prompts

O servidor incorpora um conjunto de runbooks: fluxos de trabalho guiados para tarefas comuns do Prometheus, expressos em termos das ferramentas do servidor. Cada runbook orienta o modelo sobre as ferramentas relevantes e, em seguida, sugere tópicos para explorar com consultas de exemplo, em vez de prescrever uma sequência fixa de etapas. Os runbooks cobrem tarefas como verificações de saúde do sistema, triagem de dados ausentes, investigação de taxas de erro, otimização de alta cardinalidade, revisão de regras de gravação/alerta e ajuste de configuração/desempenho.

Cada runbook é empacotado como uma Agent Skill completa: um diretório contendo um SKILL.md com frontmatter name/description. Os runbooks são expostos de três maneiras:

• Ferramentas: o modelo pode descobri-los e lê-los por conta própria por meio das ferramentas runbooks_list/runbooks_read quando uma solicitação corresponde ao propósito de um runbook. Ferramentas são o caminho mais portátil e funcionam em todos os clientes MCP.
• Recursos de skill: de acordo com o rascunho da extensão de skills SEP-2640, cada runbook é um recurso skill://<name>/SKILL.md, enumerado pelo índice de descoberta skill://index.json bem conhecido, e o servidor declara o recurso de extensão io.modelcontextprotocol/skills. Hosts com suporte a skills podem consumi-los como skills de sistema de arquivos local; outros clientes ainda podem lê-los como recursos MCP comuns.
• Prompts MCP: cada runbook também é registrado como um prompt MCP sob seu nome de skill (por exemplo, check-system-health, optimize-high-cardinality), para que clientes com suporte a prompts possam invocar um fluxo de trabalho guiado diretamente (frequentemente exibido como comandos de barra).

Backends Compatíveis com Prometheus

Existem muitos backends compatíveis com Prometheus que podem ser usados para estender o prometheus de várias maneiras, muitas vezes com os objetivos de oferecer armazenamento de longo prazo ou agregação de consultas de múltiplas instâncias do prometheus. Alguns exemplos podem ser encontrados no Remote Storage da documentação do prometheus.

Muitos desses serviços também oferecem uma API "compatível com prometheus" que pode ser usada para consultar/interagir com os dados usando promQL nativo. Em geral, este servidor MCP deve, no mínimo, funcionar para outros serviços compatíveis com a API do prometheus para executar consultas e interagir com os endpoints de séries/rótulos/metadados para descoberta de métricas e rótulos. Além disso, pode haver diferenças de API, pois os diferentes sistemas implementam diferentes partes/extensões da API para suas necessidades.

Exemplos:

• Thanos não usa uma configuração centralizada, então o endpoint de configuração não é implementado e, portanto, a ferramenta de configuração falha.
• Mimir e Cortex implementam endpoints extras para gerenciar/adicionar/remover regras.

Para contornar isso e fornecer uma melhor experiência em alguns dos sistemas compatíveis com Prometheus comumente usados, este projeto pode adicionar suporte direto para sistemas selecionados para fornecer ferramentas diferentes/mais. A escolha de uma implementação de backend prometheus específica pode ser feita com a flag --prometheus.backend. A lista de implementações de backend disponíveis em uma determinada versão do servidor MCP pode ser encontrada na saída da flag --help. Qualificações e critérios de suporte ainda estão em consideração; abra uma issue para solicitar suporte/recursos para um backend específico para discussão adicional.

Diferenças de Implementação do Backend Prometheus

Recursos

Instalação e Uso

Este servidor MCP é mais útil quando totalmente integrado a ferramentas e/ou instalado como um servidor de ferramentas com outro sistema. Os procedimentos de instalação e o suporte à integração variam dependendo das ferramentas utilizadas. Por exemplo:

• alguns sistemas só conseguem interagir com ferramentas MCP e não com recursos/prompts
• alguns sistemas usam o formato de arquivo de configuração mcp.json para gerenciar servidores MCP e outros exigem formatos personalizados
• alguns sistemas não falam MCP diretamente e exigem ferramentas como mcp-to-openapi para fazer proxy

Consulte a documentação da ferramenta utilizada/integrada para obter instruções específicas e o nível de suporte.

Binário

Baixe uma versão adequada para o seu sistema na página Releases. Consulte Flags para obter mais informações sobre as flags disponíveis e suas variáveis de ambiente correspondentes.

/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 Flags para obter mais informações sobre as flags disponíveis e suas variáveis de ambiente correspondentes.

# 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)

Um Helm chart está disponível para implantação no Kubernetes. O chart é publicado como um artefato OCI em cada release.

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

Consulte o README do chart para obter a lista completa de valores de configuração e exemplos.

Kubernetes (Manifestos Brutos)

Se preferir implantar sem Helm, manifestos Kubernetes de exemplo estão disponíveis:

• Implantação Kubernetes
• Implantação OpenShift

Pacotes de Sistema

Baixe uma versão adequada para o seu sistema na página Releases. Um arquivo de serviço Systemd está incluído nos pacotes de sistema que são compilados.

# 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: Embora pacotes sejam compilados para vários sistemas, atualmente não há planos de tentar submeter pacotes aos repositórios de pacotes upstream.

Segurança e Autenticação

Conectando a Instâncias Prometheus Seguras

O servidor MCP suporta arquivos de configuração HTTP do Prometheus para conectar a instâncias Prometheus protegidas. Um exemplo de configuração pode ser encontrado na pasta de exemplos aqui. Use a flag de linha de comando --http.config para fornecer um arquivo de configuração HTTP. Consulte Flags para obter mais informações.

Encaminhamento de Credenciais do Cliente

Ao usar o transporte HTTP, o servidor MCP encaminha o cabeçalho Authorization em cada solicitação MCP para o Prometheus nas chamadas de API dessa solicitação. Solicitações sem o cabeçalho Authorization e todas as solicitações pelo transporte stdio usam o cliente padrão construído a partir das flags (consulte Conectando a Instâncias Prometheus Seguras).

O servidor encaminha as credenciais do cliente ao Prometheus como estão e não as valida. Uma credencial que não inclui um esquema de autenticação é enviada como um token Bearer. Qualquer pessoa que consiga acessar o endpoint MCP pode consultar o Prometheus com pelo menos as credenciais do cliente padrão, portanto restrinja o acesso ao endpoint com um arquivo de configuração web ou controles de nível de rede. Observe que a autenticação básica no arquivo de configuração web (basic_auth_users) conflita com o encaminhamento de credenciais: o mesmo cabeçalho Authorization que um cliente usa para autenticar no servidor MCP é então encaminhado ao Prometheus no lugar das credenciais do cliente padrão. Configurações web somente TLS não usam o cabeçalho Authorization e não são afetadas.

Protegendo os Endpoints do Servidor MCP

O servidor MCP suporta arquivos de Configuração Web do Prometheus para expor seus endpoints atrás de autenticação básica opcional e configurações TLS personalizadas. Use a flag de linha de comando --web.config.file para fornecer um arquivo de configuração HTTP. Consulte Flags para obter mais informações.

Telemetria

Endpoints de Saúde

O servidor web expõe endpoints de saúde no endereço de escuta configurado, seguindo a convenção /-/healthy e /-/ready usada em todo o ecossistema Prometheus:

Esses endpoints mapeiam diretamente para as sondas de liveness/readiness do Kubernetes. A métrica prom_mcp_server_ready relata o mesmo estado de readiness.

Métricas

Quando em execução, o servidor expõe métricas do Prometheus no endereço de escuta e no caminho de telemetria configurados (:8080/metrics, por padrão). Consulte Flags para obter mais informações sobre como alterar a interface de escuta, a porta ou o caminho de telemetria.

Painel Grafana

Um painel Grafana pré-construído está incluído no diretório grafana/ para visualizar as métricas expostas pelo servidor MCP. Importe o json do painel para o grafana e ele deve estar pronto para uso.

Logs

Este projeto faz uso intenso de logging estruturado e em níveis. Consulte Flags para obter mais informações sobre como definir o formato do log, o nível e o arquivo opcional.

Desenvolvimento

Ambiente de Desenvolvimento com Devbox + Direnv

Se você usa Devbox e Direnv, basta entrar no diretório do repositório para configurar o software necessário.

LLM Local com Ollama

Consulte mcp.json para um exemplo de configuração MCP para uso com ferramentas. Requer ollama instalado.

NOTA:

Para substituir o LLM padrão (ollama:gpt-oss:20b), execute export OLLAMA_MODEL="ollama:your_model" to override it before running make .

make inspector

make mcphost

Gemini com gemini-cli

Consulte settings.json para um exemplo de arquivo de configuração para executar gemini-cli com o prometheus-mcp-server. Requer gemini-cli instalado.

make gemini

Configuração Manual

Software necessário:

• Ambiente Go funcional
• Docker para testes locais/linting/construção de imagens/etc
• GNU Make
• ollama
• mcp inspector
• mcphost

Compilação

Este projeto usa o conjunto de ferramentas de compilação padrão do Prometheus: promu conduzido por Makefile / Makefile.common. O binário incorpora um snapshot fixado de prometheus/docs, que os alvos de compilação baixam e extraem automaticamente (o pin está em DOCS_VERSION no 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

Os alvos auxiliares específicos do projeto (empacotamento helm e as integrações locais de cliente LLM) são listados por 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

Flags de Linha de Comando

As flags de linha de comando disponíveis estão documentadas na flag de ajuda:

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