Prometheus MCP Server

Um servidor MCP para integração com Prometheus para consultar métricas.

Documentação

Servidor MCP do Prometheus

Dê aos assistentes de IA o poder de consultar suas métricas do Prometheus.

Um servidor Model Context Protocol (MCP) que fornece acesso às suas métricas e consultas do Prometheus por meio de interfaces MCP padronizadas, permitindo que assistentes de IA executem consultas PromQL e analisem seus dados de métricas.

Começando

Pré-requisitos

Servidor Prometheus acessível a partir do seu ambiente
Cliente compatível com MCP (Claude Desktop, VS Code, Cursor, Windsurf, etc.)

Métodos de Instalação

Claude Desktop

Adicione à sua configuração do Claude Desktop:

{
  "mcpServers": {
    "prometheus": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "PROMETHEUS_URL",
        "ghcr.io/pab1it0/prometheus-mcp-server:latest"
      ],
      "env": {
        "PROMETHEUS_URL": "<your-prometheus-url>"
      }
    }
  }
}

Claude Code

Instale via CLI do Claude Code:

claude mcp add prometheus --env PROMETHEUS_URL=http://your-prometheus:9090 -- docker run -i --rm -e PROMETHEUS_URL ghcr.io/pab1it0/prometheus-mcp-server:latest

VS Code / Cursor / Windsurf

Adicione às suas configurações de MCP no IDE respectivo:

{
  "prometheus": {
    "command": "docker",
    "args": [
      "run",
      "-i",
      "--rm",
      "-e",
      "PROMETHEUS_URL",
      "ghcr.io/pab1it0/prometheus-mcp-server:latest"
    ],
    "env": {
      "PROMETHEUS_URL": "<your-prometheus-url>"
    }
  }
}

Docker Desktop

A maneira mais fácil de executar o servidor MCP do Prometheus é através do Docker Desktop:

Via Catálogo MCP: Visite o Servidor MCP do Prometheus no Docker Hub e clique no botão acima
Via MCP Toolkit: Use a extensão MCP Toolkit do Docker Desktop para descobrir e instalar o servidor
Configure sua conexão usando variáveis de ambiente (veja as Opções de Configuração abaixo)

Configuração Manual com Docker

Execute diretamente com Docker:

# With environment variables
docker run -i --rm \
  -e PROMETHEUS_URL="http://your-prometheus:9090" \
  ghcr.io/pab1it0/prometheus-mcp-server:latest

# With authentication
docker run -i --rm \
  -e PROMETHEUS_URL="http://your-prometheus:9090" \
  -e PROMETHEUS_USERNAME="admin" \
  -e PROMETHEUS_PASSWORD="password" \
  ghcr.io/pab1it0/prometheus-mcp-server:latest

Helm Chart (Kubernetes)

Implante no Kubernetes usando o Helm chart do registro OCI:

helm install prometheus-mcp-server \
  oci://ghcr.io/pab1it0/charts/prometheus-mcp-server \
  --version 1.1.1 \
  --set prometheus.url="http://prometheus:9090"

Com autenticação:

helm install prometheus-mcp-server \
  oci://ghcr.io/pab1it0/charts/prometheus-mcp-server \
  --version 1.1.1 \
  --set prometheus.url="http://prometheus:9090" \
  --set auth.username="admin" \
  --set auth.password="secret"

Com um arquivo de valores personalizado:

helm install prometheus-mcp-server \
  oci://ghcr.io/pab1it0/charts/prometheus-mcp-server \
  --version 1.1.1 \
  -f values.yaml

Consulte os valores do chart para todas as opções de configuração disponíveis.

Opções de Configuração

Variável	Descrição	Obrigatório
`PROMETHEUS_URL`	URL do seu servidor Prometheus	Sim
`PROMETHEUS_URL_SSL_VERIFY`	Defina como False para desabilitar a verificação SSL	Não
`PROMETHEUS_DISABLE_LINKS`	Defina como True para desabilitar links da interface do Prometheus nos resultados de consulta (economiza tokens de contexto)	Não
`PROMETHEUS_REQUEST_TIMEOUT`	Tempo limite de solicitação em segundos para evitar solicitações pendentes (proteção contra DDoS)	Não (padrão: 30)
`PROMETHEUS_USERNAME`	Nome de usuário para autenticação básica	Não
`PROMETHEUS_PASSWORD`	Senha para autenticação básica	Não
`PROMETHEUS_TOKEN`	Token Bearer para autenticação	Não
`PROMETHEUS_CLIENT_CERT`	Caminho para o arquivo de certificado do cliente para autenticação TLS mútua	Não
`PROMETHEUS_CLIENT_KEY`	Caminho para o arquivo de chave privada do cliente para autenticação TLS mútua	Não
`REQUESTS_CA_BUNDLE`	Caminho para o arquivo de pacote CA para verificar o certificado TLS do servidor (variável de ambiente padrão da biblioteca `requests`)	Não
`ORG_ID`	ID da organização para ambientes multi-tenant	Não
`PROMETHEUS_MCP_SERVER_TRANSPORT`	Modo de transporte (stdio, http, sse)	Não (padrão: stdio)
`PROMETHEUS_MCP_BIND_HOST`	Host para transporte HTTP	Não (padrão: 127.0.0.1)
`PROMETHEUS_MCP_BIND_PORT`	Porta para transporte HTTP	Não (padrão: 8080)
`PROMETHEUS_MCP_STATELESS_HTTP`	Habilite o modo HTTP sem estado para suporte a múltiplas réplicas	Não (padrão: False)
`PROMETHEUS_CUSTOM_HEADERS`	Cabeçalhos personalizados como string JSON	Não
`TOOL_PREFIX`	Prefixo para todos os nomes de ferramentas (ex.: `staging` resulta em `staging_execute_query`). Útil para executar múltiplas instâncias direcionadas a diferentes ambientes no Cursor	Não

Ferramentas Disponíveis

Ferramenta	Categoria	Descrição
`health_check`	Sistema	Endpoint de verificação de saúde para monitoramento de contêineres e verificação de status
`execute_query`	Consulta	Executa uma consulta instantânea PromQL contra o Prometheus
`execute_range_query`	Consulta	Executa uma consulta de intervalo PromQL com horário de início, horário de término e intervalo de passo
`list_metrics`	Descoberta	Lista todas as métricas disponíveis no Prometheus com suporte a paginação e filtragem
`get_metric_metadata`	Descoberta	Obtém metadados para uma métrica ou metadados em lote com filtragem opcional
`get_targets`	Descoberta	Obtém alvos de scrape, com filtragem `state`/`scrape_pool` no lado do servidor e paginação opcional

A lista de ferramentas é configurável, para que você possa escolher quais ferramentas deseja disponibilizar ao cliente MCP. Isso é útil se você não usa determinada funcionalidade ou se não deseja ocupar muito da janela de contexto.

Recursos

Executa consultas PromQL contra o Prometheus
Descobre e explora métricas
- Lista métricas disponíveis
- Obtém metadados para métricas específicas
- Pesquisa metadados de métricas por nome ou descrição em uma única chamada
- Visualiza resultados de consultas instantâneas
- Visualiza resultados de consultas de intervalo com diferentes intervalos de passo
Suporte a autenticação
- Autenticação básica a partir de variáveis de ambiente
- Autenticação por token Bearer a partir de variáveis de ambiente
Suporte a conteinerização com Docker
Fornece ferramentas interativas para assistentes de IA

Desenvolvimento

Contribuições são bem-vindas! Consulte nosso Guia de Contribuição para informações detalhadas sobre como começar, padrões de codificação e o processo de pull request.

Este projeto usa uv para gerenciar dependências. Instale o uv seguindo as instruções para sua plataforma:

curl -LsSf https://astral.sh/uv/install.sh | sh

Você pode então criar um ambiente virtual e instalar as dependências com:

uv venv
source .venv/bin/activate  # On Unix/macOS
.venv\Scripts\activate     # On Windows
uv pip install -e .

Testes

O projeto inclui uma suíte de testes abrangente que garante a funcionalidade e ajuda a prevenir regressões.

Execute os testes com pytest:

# Install development dependencies
uv pip install -e ".[dev]"

# Run the tests
pytest

# Run with coverage report
pytest --cov=src --cov-report=term-missing

Ao adicionar novos recursos, adicione também os testes correspondentes.

Licença

MIT