GreptimeDB

greptimedb-mcp-server

Um servidor MCP (Model Context Protocol) para GreptimeDB — um banco de dados de observabilidade de código aberto que lida com métricas, logs e traces em um único mecanismo.

Permite que assistentes de IA consultem e analisem o GreptimeDB usando SQL, TQL (compatível com PromQL) e consultas RANGE, com recursos de segurança integrados, como aplicação de somente leitura e mascaramento de dados.

Início Rápido

# Install
pip install greptimedb-mcp-server

# Run (connects to localhost:4002 by default)
greptimedb-mcp-server --host localhost --database public

Para o Claude Desktop, adicione isto à sua configuração (~/Library/Application Support/Claude/claude_desktop_config.json no macOS):

{
  "mcpServers": {
    "greptimedb": {
      "command": "greptimedb-mcp-server",
      "args": ["--host", "localhost", "--database", "public"]
    }
  }
}

Recursos

Ferramentas

Ferramenta	Descrição
execute_sql	Executa consultas SQL com opções de formato (csv/json/markdown) e limite
execute_tql	Executa consultas TQL (compatível com PromQL) para análise de séries temporais
query_range	Executa consultas de agregação por janela de tempo com sintaxe RANGE/ALIGN
search_table_semantics	Encontra tabelas por conceito de observabilidade, classificadas por termos correspondentes; pesquisa nomes de tabelas, opções semânticas e declarações de entidades
query_semantic_graph	Consulta o grafo semântico: summary (o que contém), entities (nós), relationships (arestas) em uma janela de tempo obrigatória
describe_table	Inspeciona o perfil de uma tabela: esquema, metadados semânticos, amostras de linhas mais recentes e orientação de consulta
explain_query	Analisa planos de execução de consultas SQL ou TQL (analyze=true para estatísticas de tempo de execução; adicione verbose=true junto com analyze=true para métricas de varredura por partição e contadores de poda de índice)
health_check	Verifica o status da conexão com o banco de dados e a versão do servidor

search_table_semantics e os metadados semânticos em describe_table leem information_schema.table_semantics. Uma tabela aparece lá quando possui uma opção greptime.semantic.* ou uma convenção integrada deriva uma declaração de entidade para ela; outras tabelas estão ausentes. O servidor lê a lista de colunas da visão uma vez por processo e seleciona apenas as colunas que expõe. entity_declarations requer GreptimeDB 1.3; em versões anteriores, é relatado como uma coluna ausente em vez de um conjunto de declarações vazio.

query_semantic_graph lê greptime_private.semantic_entities e greptime_private.semantic_relationships, que exigem GreptimeDB 1.3. Na inicialização, o servidor verifica se ambas as visões existem, contêm as colunas que lê e são legíveis pela conta conectada; quando não são, a ferramenta não é oferecida e o motivo é registrado. Sua janela de tempo é obrigatória e semiaberta, [start_time, end_time) sobre observed_at, e as linhas são agregadas nos buckets de observação de 60 segundos nessa janela.

Gerenciamento de Pipelines

Ferramenta	Descrição
list_pipelines	Lista todos os pipelines ou obtém detalhes de um pipeline específico
create_pipeline	Cria um novo pipeline com configuração YAML
dryrun_pipeline	Testa um pipeline com dados de amostra sem gravar no banco de dados
delete_pipeline	Exclui uma versão específica de um pipeline

Gerenciamento de Dashboards

Ferramenta	Descrição
list_dashboards	Lista todas as definições de dashboard do Perses
create_dashboard	Cria ou atualiza uma definição de dashboard do Perses
delete_dashboard	Exclui uma definição de dashboard

Recursos e Prompts

• Recursos: Navegue pelas tabelas via URIs greptime://<table>/data
• Prompts: Modelos Jinja integrados para tarefas comuns — pipeline_creator, log_pipeline, metrics_analysis, promql_analysis, trace_analysis, table_operation, schema_design_advisor, observability_correlation, ingestion_troubleshooting, query_performance_tuning

Para integração com LLM e uso de prompts, consulte docs/llm-instructions.md.

Essas ferramentas cobrem consulta e gerenciamento de dados em um GreptimeDB existente. Para implantação, configuração do servidor, protocolos de escrita, sintaxe de pipelines, design de esquema e diagnóstico de desempenho, aponte o assistente para o índice de habilidades do GreptimeDB em https://docs.greptime.com/SKILL.md.

Configuração

Variáveis de Ambiente

GREPTIMEDB_HOST=localhost      # Database host
GREPTIMEDB_PORT=4002           # MySQL protocol port (default: 4002)
GREPTIMEDB_USER=root           # Database user
GREPTIMEDB_PASSWORD=           # Database password
GREPTIMEDB_DATABASE=public     # Database name
GREPTIMEDB_TIMEZONE=UTC        # Session timezone

# Optional
GREPTIMEDB_HTTP_PORT=4000      # HTTP API port for pipeline/dashboard management
GREPTIMEDB_HTTP_PROTOCOL=http  # HTTP protocol (http/https)
GREPTIMEDB_POOL_SIZE=5         # Connection pool size
GREPTIMEDB_MASK_ENABLED=true   # Enable sensitive data masking
GREPTIMEDB_MASK_PATTERNS=      # Additional patterns (comma-separated)
GREPTIMEDB_AUDIT_ENABLED=true  # Enable audit logging
GREPTIMEDB_ALLOW_WRITE=false   # Allow write/DDL via execute_sql (DANGEROUS, local/test only)

# Transport (for HTTP server mode)
GREPTIMEDB_TRANSPORT=stdio     # stdio, sse, or streamable-http
GREPTIMEDB_LISTEN_HOST=0.0.0.0 # HTTP server bind host
GREPTIMEDB_LISTEN_PORT=8080    # HTTP server bind port
GREPTIMEDB_ALLOWED_HOSTS=      # DNS rebinding protection (comma-separated)
GREPTIMEDB_ALLOWED_ORIGINS=    # CORS allowed origins (comma-separated)

Argumentos de CLI

greptimedb-mcp-server \
  --host localhost \
  --port 4002 \
  --database public \
  --user root \
  --password "" \
  --timezone UTC \
  --pool-size 5 \
  --mask-enabled true \
  --allow-write false \
  --transport stdio

Modo Servidor HTTP

Para implantações em contêineres ou Kubernetes:

# Streamable HTTP (recommended for production)
greptimedb-mcp-server --transport streamable-http --listen-port 8080

# SSE mode (legacy)
greptimedb-mcp-server --transport sse --listen-port 3000

Proteção contra Rebinding de DNS

Por padrão, a proteção contra rebinding de DNS está desabilitada para compatibilidade com proxies, gateways e serviços Kubernetes. Para habilitá-la, use --allowed-hosts:

# Enable DNS rebinding protection with allowed hosts
greptimedb-mcp-server --transport streamable-http \
  --allowed-hosts "localhost:*,127.0.0.1:*,my-service.namespace:*"

# With custom allowed origins for CORS
greptimedb-mcp-server --transport streamable-http \
  --allowed-hosts "my-service.namespace:*" \
  --allowed-origins "http://localhost:*,https://my-app.example.com"

# Or via environment variables
GREPTIMEDB_ALLOWED_HOSTS="localhost:*,my-service.namespace:*" \
GREPTIMEDB_ALLOWED_ORIGINS="http://localhost:*" \
  greptimedb-mcp-server --transport streamable-http

Se você encontrar erros de 421 Invalid Host Header, desabilite a proteção (padrão) ou adicione seu host à lista de permitidos.

Segurança

Usuário de Banco de Dados Somente Leitura (Recomendado)

Crie um usuário somente leitura no GreptimeDB usando o provedor de usuário estático:

mcp_readonly:readonly=your_secure_password

Portão de Segurança em Nível de Aplicação

Todas as consultas passam por um portão de segurança que:

• Bloqueia: DROP, DELETE, TRUNCATE, UPDATE, INSERT, ALTER, CREATE, GRANT, REVOKE, EXEC, LOAD, COPY
• Bloqueia: Tentativas de bypass codificadas (hex, UNHEX, CHAR)
• Permite: SELECT, SHOW, DESCRIBE, TQL, EXPLAIN, UNION

Modo de Escrita (Desabilitado por Padrão)

O servidor é somente leitura por padrão. Para desenvolvimento local ou testes, você pode permitir SQL de escrita/destrutivo (DDL/DML como CREATE, DROP, ALTER, INSERT, UPDATE, DELETE) por meio da ferramenta execute_sql habilitando o modo de escrita:

# Environment variable
GREPTIMEDB_ALLOW_WRITE=true greptimedb-mcp-server

# Or CLI argument
greptimedb-mcp-server --allow-write true

Quando habilitado, o portão de segurança é ignorado para execute_sql, e o servidor registra um aviso na inicialização.

⚠️ Perigo: Isso permite que um assistente de IA execute declarações destrutivas contra seu banco de dados. Nunca habilite isso contra dados de produção. Combine com um usuário de banco de dados somente leitura se você precisar apenas de acesso de leitura.

Mascaramento de Dados

Colunas sensíveis são mascaradas automaticamente (******) com base em padrões de nomes de colunas:

• Autenticação: password, secret, token, api_key, credential
• Financeiro: credit_card, cvv, bank_account
• Pessoal: ssn, id_card, passport

Configure com --mask-patterns phone,email para adicionar padrões personalizados.

Registro de Auditoria

Todas as invocações de ferramentas são registradas:

2025-12-10 10:30:45 - greptimedb_mcp_server.audit - INFO - [AUDIT] execute_sql | query="SELECT * FROM cpu LIMIT 10" | success=True | duration_ms=45.2

Desabilite com --audit-enabled false.

Desenvolvimento

# Clone and setup
git clone https://github.com/GreptimeTeam/greptimedb-mcp-server.git
cd greptimedb-mcp-server
uv venv && source .venv/bin/activate
uv sync

# Run tests
pytest

# Format & lint
uv run black .
uv run flake8 src

# Debug with MCP Inspector
npx @modelcontextprotocol/inspector uv --directory . run -m greptimedb_mcp_server.server

Licença

Licença MIT - consulte LICENSE.md.

Agradecimentos

Inspirado por:

• ktanaka101/mcp-server-duckdb
• designcomputer/mysql_mcp_server
• mikeskarl/mcp-prompt-templates