Tempo MCP Server

Um servidor MCP para consultar dados de rastreamento distribuído do Grafana Tempo.

Documentação

Servidor MCP Tempo

Uma implementação de servidor baseada em Go para o Model Context Protocol (MCP) com integração com Grafana Tempo.

Visão Geral

Este servidor MCP permite que assistentes de IA consultem e analisem dados de rastreamento distribuído do Grafana Tempo. Ele segue o Model Context Protocol para fornecer definições de ferramentas que podem ser usadas por clientes de IA compatíveis, como o Claude Desktop.

Começando

Pré-requisitos

Go 1.21 ou superior
Docker e Docker Compose (para testes locais)

Compilando e Executando

Compile e execute o servidor:

# Build the server
go build -o tempo-mcp-server ./cmd/server

# Run the server
./tempo-mcp-server

Ou execute diretamente com Go:

go run ./cmd/server

O servidor agora suporta dois modos de comunicação:

Entrada/saída padrão (stdin/stdout) seguindo o Model Context Protocol (MCP)
Servidor HTTP com endpoint Server-Sent Events (SSE) para integração com ferramentas como n8n

A porta padrão para o servidor HTTP é 8080, mas pode ser configurada usando a variável de ambiente SSE_PORT.

Endpoints do Servidor

Quando executado em modo HTTP, o servidor expõe os seguintes endpoints:

Endpoint SSE: http://localhost:8080/sse - Para streaming de eventos em tempo real
Endpoint MCP: http://localhost:8080/mcp - Para mensagens do protocolo MCP

Suporte a Docker

Você pode compilar e executar o servidor MCP usando Docker:

# Build the Docker image
docker build -t tempo-mcp-server .

# Run the server
docker run -p 8080:8080 --rm -i tempo-mcp-server

Alternativamente, você pode usar Docker Compose para um ambiente de teste completo:

# Build and run with Docker Compose
docker-compose up --build

Estrutura do Projeto

.
├── cmd/
│   ├── server/       # MCP server implementation
│   └── client/       # Client for testing the MCP server
├── internal/
│   └── handlers/     # Tool handlers
├── pkg/
│   └── utils/        # Utility functions and shared code
└── go.mod            # Go module definition

Servidor MCP

O Servidor MCP Tempo implementa o Model Context Protocol (MCP) e fornece as seguintes ferramentas:

Ferramenta de Consulta Tempo

A ferramenta tempo_query permite consultar dados de rastreamento do Grafana Tempo:

Parâmetros obrigatórios:
- query: String de consulta Tempo (ex.: {service.name="frontend"}, {duration>1s})
Parâmetros opcionais:
- url: URL do servidor Tempo (padrão: da variável de ambiente TEMPO_URL ou http://localhost:3200)
- start: Hora de início para a consulta (padrão: 1h atrás)
- end: Hora de término para a consulta (padrão: agora)
- limit: Número máximo de rastreamentos a retornar (padrão: 20)
- username: Nome de usuário para autenticação básica (opcional)
- password: Senha para autenticação básica (opcional)
- token: Token Bearer para autenticação (opcional)

Variáveis de Ambiente

A ferramenta de consulta Tempo suporta as seguintes variáveis de ambiente:

TEMPO_URL: URL padrão do servidor Tempo a ser usada se não for especificada na solicitação
SSE_PORT: Porta para o servidor HTTP/SSE (padrão: 8080)

Testes

./run-client.sh tempo_query "{resource.service.name=\\\"example-service\\\"}"

Usando com Claude Desktop

Você pode usar este servidor MCP com o Claude Desktop para adicionar ferramentas de consulta Tempo. Siga estes passos:

Compile o servidor ou a imagem Docker
Configure o Claude Desktop para usar o servidor adicionando-o ao seu arquivo de configuração do Claude Desktop

Exemplo de configuração do Claude Desktop:

{
  "mcpServers": {
    "temposerver": {
      "command": "path/to/tempo-mcp-server",
      "args": [],
      "env": {
        "TEMPO_URL": "http://localhost:3200"
      },
      "disabled": false,
      "autoApprove": ["tempo_query"]
    }
  }
}

Para Docker:

{
  "mcpServers": {
    "temposerver": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "TEMPO_URL=http://host.docker.internal:3200", "tempo-mcp-server"],
      "disabled": false,
      "autoApprove": ["tempo_query"]
    }
  }
}

O arquivo de configuração do Claude Desktop está localizado em:

No macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
No Windows: %APPDATA%\Claude\claude_desktop_config.json
No Linux: ~/.config/Claude/claude_desktop_config.json

Usando com Cursor

Você também pode integrar o servidor MCP Tempo com o editor Cursor. Para isso, adicione a seguinte configuração às suas configurações do Cursor:

{
  "mcpServers": {
    "tempo-mcp-server": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "TEMPO_URL=http://host.docker.internal:3200", "tempo-mcp-server:latest"]
    }
  }
}

Usando com n8n

Para usar o servidor MCP Tempo com n8n, você pode conectar-se a ele usando o nó MCP Client Tool:

Adicione um nó MCP Client Tool ao seu fluxo de trabalho n8n
Configure o nó com estes parâmetros:
- Endpoint SSE: http://your-server-address:8080/sse (substitua pelo endereço real do seu servidor)
- Autenticação: Escolha a autenticação apropriada, se necessário
- Ferramentas a Incluir: Escolha quais ferramentas Tempo expor ao Agente de IA
Conecte o nó MCP Client Tool a um nó AI Agent que usará os recursos de consulta Tempo

Exemplo de fluxo de trabalho: Trigger → MCP Client Tool (servidor Tempo) → AI Agent (Claude)

Exemplo de Uso

Uma vez configurado, você pode usar as ferramentas no Claude com consultas como:

"Consulte o Tempo para rastreamentos com a consulta {duration>1s}"
"Encontre rastreamentos do serviço frontend no Tempo usando a consulta {service.name=\"frontend\"}"
"Mostre-me os 50 rastreamentos mais recentes do Tempo com {http.status_code=500}"

Licença

Este projeto é licenciado sob a Licença MIT.