GreptimeDB MCP Server

oficial

Fornece aos assistentes de IA uma maneira segura e estruturada de explorar e analisar dados no GreptimeDB.

Documentação

greptimedb-mcp-server

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

Permite que assistentes de IA consultem e analisem o GreptimeDB usando consultas SQL, TQL (compatível com PromQL) e RANGE, com recursos de segurança integrados, como imposiçã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"]
    }
  }
}

Funcionalidades

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 em janela de tempo com sintaxe RANGE/ALIGN
`describe_table`	Inspeciona o perfil de uma tabela: esquema, metadados semânticos, linhas de amostra 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

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 Perses
`create_dashboard`	Cria ou atualiza uma definição de dashboard Perses
`delete_dashboard`	Exclui uma definição de dashboard

Recursos e Prompts

Recursos: Navegue pelas tabelas via URIs greptime://<table>/data
Prompts: Templates 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, veja docs/llm-instructions.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. Requer mcp>=1.8.0:

# 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 DNS Rebinding

Por padrão, a proteção contra DNS rebinding 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 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) através 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 é contornado para execute_sql, e o servidor registra um aviso na inicialização.

⚠️ Perigo: Isso permite que um assistente de IA execute instruções destrutivas contra seu banco de dados. Nunca habilite isso em 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 automaticamente mascaradas (******) com base em padrões de nome de coluna:

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 - veja LICENSE.md.

Agradecimentos

Inspirado por: