GreptimeDB

greptimedb-mcp-server

Un servidor de Protocolo de Contexto de Modelo (MCP) para GreptimeDB — una base de datos de observabilidad de código abierto que maneja métricas, registros y trazas en un solo motor.

Permite a los asistentes de IA consultar y analizar GreptimeDB usando SQL, TQL (compatible con PromQL) y consultas RANGE, con funciones de seguridad integradas como aplicación de solo lectura y enmascaramiento de datos.

Inicio Rápido

# Install
pip install greptimedb-mcp-server

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

Para Claude Desktop, agrega esto a tu configuración (~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

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

Características

Herramientas

Herramienta	Descripción
execute_sql	Ejecuta consultas SQL con opciones de formato (csv/json/markdown) y límite
execute_tql	Ejecuta consultas TQL (compatibles con PromQL) para análisis de series temporales
query_range	Ejecuta consultas de agregación por ventana de tiempo con sintaxis RANGE/ALIGN
search_table_semantics	Encuentra tablas por concepto de observabilidad, clasificadas por términos coincidentes; busca nombres de tablas, opciones semánticas y declaraciones de entidades. schema selecciona la base de datos a buscar
query_semantic_graph	Consulta el grafo semántico: summary (qué contiene), entities (nodos), relationships (aristas) sobre una ventana de tiempo requerida
describe_table	Inspecciona un perfil de tabla: esquema, metadatos semánticos, últimas filas de muestra y guía de consulta
explain_query	Analiza planes de ejecución de consultas SQL o TQL (analyze=true para estadísticas de tiempo de ejecución; agrega verbose=true junto con analyze=true para métricas de escaneo por partición y contadores de poda de índices)
health_check	Verifica el estado de conexión de la base de datos y la versión del servidor

search_table_semantics y los metadatos semánticos en describe_table leen information_schema.table_semantics. Una tabla aparece allí cuando lleva una opción greptime.semantic.* o una convención integrada deriva una declaración de entidad para ella; otras tablas están ausentes. El servidor lee la lista de columnas de la vista una vez por proceso y selecciona solo las columnas que expone. entity_declarations requiere GreptimeDB 1.3; en versiones anteriores se reporta como una columna faltante en lugar de un conjunto de declaraciones vacío.

Los resultados de las herramientas están limitados por GREPTIMEDB_MAX_RESULT_BYTES (predeterminado 1048576, o 1 MiB). Un resultado de consulta que excede el presupuesto devuelve menos filas y lo reporta en truncated y truncation_reason; un resultado sin filas que descartar se corta con un aviso al final. El presupuesto es una salvaguarda contra un resultado demasiado grande para consumirse, así que redúcelo si tu cliente MCP rechaza resultados antes de alcanzarlo.

Consultas entre bases de datos

El servidor se conecta a una base de datos, pero las lecturas no están restringidas a ella:

Herramienta	Cómo llegar a otra base de datos
execute_sql, query_range, describe_table	Califica la tabla como schema.table
execute_tql	metric{__schema__="other_db"}, que acepta solo =
search_table_semantics	Pasa schema
query_semantic_graph	Ya es de todo el catálogo; no se necesita alcance

La cuenta conectada necesita permiso de lectura en la base de datos de destino. Usa SHOW DATABASES para listarlas.

query_semantic_graph lee greptime_private.semantic_entities y greptime_private.semantic_relationships, que requieren GreptimeDB 1.3. Al inicio, el servidor verifica que ambas vistas existan, contengan las columnas que lee y sean legibles por la cuenta conectada; cuando no es así, la herramienta no se ofrece y el motivo se registra. Su ventana de tiempo es obligatoria y semiabierta, [start_time, end_time) sobre observed_at, y las filas se agregan en los buckets de observación de 60 segundos dentro de esa ventana.

Gestión de Pipelines

Herramienta	Descripción
list_pipelines	Lista todos los pipelines u obtén detalles de un pipeline específico
create_pipeline	Crea un nuevo pipeline con configuración YAML
dryrun_pipeline	Prueba un pipeline con datos de muestra sin escribir en la base de datos
delete_pipeline	Elimina una versión específica de un pipeline

Gestión de Paneles

Herramienta	Descripción
list_dashboards	Lista todas las definiciones de paneles de Perses
create_dashboard	Crea o actualiza una definición de panel de Perses
delete_dashboard	Elimina una definición de panel

Recursos y Prompts

• Recursos: Explora tablas mediante URIs greptime://<table>/data
• Prompts: Plantillas Jinja integradas para tareas comunes — pipeline_creator, log_pipeline, metrics_analysis, promql_analysis, trace_analysis, table_operation, schema_design_advisor, observability_correlation, ingestion_troubleshooting, query_performance_tuning

Para integración con LLM y uso de prompts, consulta docs/llm-instructions.md.

Estas herramientas cubren la consulta y gestión de datos en un GreptimeDB existente. Para implementación, configuración del servidor, protocolos de escritura, sintaxis de pipelines, diseño de esquemas y diagnóstico de rendimiento, apunta al asistente al índice de habilidades de GreptimeDB en https://docs.greptime.com/SKILL.md.

Configuración

Variables de Entorno

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 writes: DDL/DML plus pipeline and dashboard changes (DANGEROUS, local/test only)
GREPTIMEDB_MAX_RESULT_BYTES=1048576 # Byte budget for a single tool result (1 MiB)

# 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 implementaciones en contenedores o 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

Protección contra Rebinding de DNS

Por defecto, la protección contra rebinding de DNS está deshabilitada para compatibilidad con proxies, puertas de enlace y servicios de Kubernetes. Para habilitarla, usa --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

Si encuentras errores 421 Invalid Host Header, deshabilita la protección (predeterminado) o agrega tu host a la lista permitida.

Seguridad

Usuario de Base de Datos de Solo Lectura (Recomendado)

Crea un usuario de solo lectura en GreptimeDB usando el proveedor de usuarios estático:

mcp_readonly:readonly=your_secure_password

Puerta de Seguridad a Nivel de Aplicación

Todas las consultas pasan por una puerta de seguridad que:

• Bloquea: DROP, DELETE, TRUNCATE, UPDATE, INSERT, ALTER, CREATE, GRANT, REVOKE, EXEC, LOAD, COPY
• Bloquea: Intentos de evasión codificados (hex, UNHEX, CHAR)
• Permite: SELECT, SHOW, DESCRIBE, TQL, EXPLAIN, UNION

Modo de Escritura (Deshabilitado por Defecto)

El servidor es de solo lectura por defecto. El modo de escritura habilita cada operación que cambia el estado almacenado:

• SQL destructivo (DDL/DML como CREATE, DROP, ALTER, INSERT, UPDATE, DELETE) a través de execute_sql
• create_pipeline, delete_pipeline, create_dashboard, delete_dashboard

# Environment variable
GREPTIMEDB_ALLOW_WRITE=true greptimedb-mcp-server

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

Cuando está habilitado, la puerta de seguridad se omite para execute_sql, y el servidor registra una advertencia al inicio. Con el modo de escritura desactivado, esas cuatro herramientas devuelven un error sin contactar al servidor; list_pipelines, list_dashboards y dryrun_pipeline son de solo lectura y permanecen disponibles.

⚠️ Peligro: Esto permite que un asistente de IA ejecute declaraciones destructivas contra tu base de datos. Nunca lo habilites contra datos de producción. Combínalo con un usuario de base de datos de solo lectura si solo necesitas acceso de lectura.

Enmascaramiento de Datos

Las columnas sensibles se enmascaran automáticamente (******) según patrones de nombres de columna:

• Autenticación: password, secret, token, api_key, credential
• Financiero: credit_card, cvv, bank_account
• Personal: ssn, id_card, passport

Configura con --mask-patterns phone,email para agregar patrones personalizados.

Registro de Auditoría

Todas las invocaciones de herramientas se registran:

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

Deshabilita con --audit-enabled false.

Desarrollo

# 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

Licencia

Licencia MIT - consulta LICENSE.md.

Agradecimientos

Inspirado en:

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