GreptimeDB MCP Server

oficial

Proporciona a los asistentes de IA una forma segura y estructurada de explorar y analizar datos en GreptimeDB.

Documentación

greptimedb-mcp-server

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

Permite a los asistentes de IA consultar y analizar GreptimeDB usando consultas SQL, TQL (compatible con PromQL) y RANGE, con funciones de seguridad integradas como la aplicación de solo lectura y el 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, añade 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`	Ejecutar consultas SQL con opciones de formato (csv/json/markdown) y límite
`execute_tql`	Ejecutar consultas TQL (compatible con PromQL) para análisis de series temporales
`query_range`	Ejecutar consultas de agregación por ventana de tiempo con sintaxis RANGE/ALIGN
`describe_table`	Inspeccionar el perfil de una tabla: esquema, metadatos semánticos, últimas filas de muestra y guía de consulta
`explain_query`	Analizar planes de ejecución de consultas SQL o TQL (`analyze=true` para estadísticas de tiempo de ejecución; añadir `verbose=true` junto con `analyze=true` para métricas de escaneo por partición y contadores de poda de índices)
`health_check`	Verificar el estado de la conexión a la base de datos y la versión del servidor

Gestión de Pipelines

Herramienta	Descripción
`list_pipelines`	Listar todos los pipelines u obtener detalles de un pipeline específico
`create_pipeline`	Crear un nuevo pipeline con configuración YAML
`dryrun_pipeline`	Probar un pipeline con datos de muestra sin escribir en la base de datos
`delete_pipeline`	Eliminar una versión específica de un pipeline

Gestión de Dashboards

Herramienta	Descripción
`list_dashboards`	Listar todas las definiciones de dashboard de Perses
`create_dashboard`	Crear o actualizar una definición de dashboard de Perses
`delete_dashboard`	Eliminar una definición de dashboard

Recursos y Prompts

Recursos: Explorar tablas a través de 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 la integración con LLM y el uso de prompts, consulta docs/llm-instructions.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 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 despliegues en contenedores o Kubernetes. Requiere 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

Protección contra Reenlace DNS

Por defecto, la protección contra reenlace DNS está deshabilitada para compatibilidad con proxies, gateways 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 (por defecto) o añade tu host a la lista de permitidos.

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 elusión codificados (hex, UNHEX, CHAR)
Permite: SELECT, SHOW, DESCRIBE, TQL, EXPLAIN, UNION

Modo Escritura (Deshabilitado por Defecto)

El servidor es de solo lectura por defecto. Para desarrollo local o pruebas, puedes permitir SQL de escritura/destructivo (DDL/DML como CREATE, DROP, ALTER, INSERT, UPDATE, DELETE) a través de la herramienta execute_sql habilitando el modo escritura:

# 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.

⚠️ Peligro: Esto permite que un asistente de IA ejecute sentencias 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 nombre 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 añadir 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 por: