GreptimeDB

greptimedb-mcp-server

Ein Model Context Protocol (MCP)-Server für GreptimeDB – eine Open-Source-Observability-Datenbank, die Metriken, Logs und Traces in einer Engine verarbeitet.

Ermöglicht KI-Assistenten, GreptimeDB mit SQL, TQL (PromQL-kompatibel) und RANGE-Abfragen zu durchsuchen und zu analysieren – mit integrierten Sicherheitsfunktionen wie Read-Only-Erzwingung und Datenmaskierung.

Schnellstart

# Install
pip install greptimedb-mcp-server

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

Für Claude Desktop fügen Sie dies zu Ihrer Konfiguration hinzu (~/Library/Application Support/Claude/claude_desktop_config.json unter macOS):

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

Funktionen

Tools

Tool	Beschreibung
execute_sql	SQL-Abfragen mit Format- (csv/json/markdown) und Limit-Optionen ausführen
execute_tql	TQL-Abfragen (PromQL-kompatibel) für Zeitreihenanalysen ausführen
query_range	Zeitfenster-Aggregationsabfragen mit RANGE/ALIGN-Syntax ausführen
search_table_semantics	Tabellen nach Observability-Konzept finden, sortiert nach übereinstimmenden Begriffen; durchsucht Tabellennamen, semantische Optionen und Entitätsdeklarationen. schema wählt die zu durchsuchende Datenbank aus
query_semantic_graph	Den semantischen Graphen abfragen: summary (was er enthält), entities (Knoten), relationships (Kanten) über ein erforderliches Zeitfenster
describe_table	Ein Tabellenprofil untersuchen: Schema, semantische Metadaten, neueste Beispieldatenzeilen und Abfragehinweise
explain_query	Ausführungspläne von SQL- oder TQL-Abfragen analysieren (analyze=true für Laufzeitstatistiken; verbose=true zusammen mit analyze=true für Scan-Metriken pro Partition und Index-Pruning-Zähler hinzufügen)
health_check	Datenbankverbindungsstatus und Serverversion prüfen

search_table_semantics und die semantischen Metadaten in describe_table lesen information_schema.table_semantics. Eine Tabelle erscheint dort, wenn sie eine greptime.semantic.*-Option trägt oder eine eingebaute Konvention eine Entitätsdeklaration für sie ableitet; andere Tabellen fehlen. Der Server liest die Spaltenliste der View einmal pro Prozess und wählt nur die Spalten aus, die er bereitstellt. entity_declarations erfordert GreptimeDB 1.3; auf früheren Versionen wird es als fehlende Spalte gemeldet und nicht als leere Deklarationsmenge.

Tool-Ergebnisse sind durch GREPTIMEDB_MAX_RESULT_BYTES begrenzt (Standard 1048576, also 1 MiB). Ein Abfrageergebnis über dem Budget gibt weniger Zeilen zurück und meldet dies in truncated und truncation_reason; ein Ergebnis ohne abzuwerfende Zeilen wird mit einem Hinweis am Ende gekürzt. Das Budget ist eine Absicherung gegen ein zu großes Ergebnis, daher sollten Sie es senken, wenn Ihr MCP-Client Ergebnisse ablehnt, bevor es erreicht wird.

Datenbankübergreifende Abfragen

Der Server verbindet sich mit einer Datenbank, aber Lesezugriffe sind nicht darauf beschränkt:

Tool	So erreichen Sie eine andere Datenbank
execute_sql, query_range, describe_table	Die Tabelle als schema.table qualifizieren
execute_tql	metric{__schema__="other_db"}, das nur = akzeptiert
search_table_semantics	schema übergeben
query_semantic_graph	Bereits katalogweit; keine Bereichsbegrenzung erforderlich

Das verbundene Konto benötigt Leseberechtigung für die Zieldatenbank. Verwenden Sie SHOW DATABASES, um diese aufzulisten.

query_semantic_graph liest greptime_private.semantic_entities und greptime_private.semantic_relationships, die GreptimeDB 1.3 erfordern. Beim Start prüft der Server, dass beide Views existieren, die gelesenen Spalten enthalten und für das verbundene Konto lesbar sind; wenn nicht, wird das Tool nicht angeboten und der Grund protokolliert. Sein Zeitfenster ist erforderlich und halboffen, [start_time, end_time) über observed_at, und Zeilen werden über die 60-Sekunden-Beobachtungsintervalle in diesem Fenster aggregiert.

Pipeline-Verwaltung

Tool	Beschreibung
list_pipelines	Alle Pipelines auflisten oder Details einer bestimmten Pipeline abrufen
create_pipeline	Eine neue Pipeline mit YAML-Konfiguration erstellen
dryrun_pipeline	Eine Pipeline mit Beispieldaten testen, ohne in die Datenbank zu schreiben
delete_pipeline	Eine bestimmte Version einer Pipeline löschen

Dashboard-Verwaltung

Tool	Beschreibung
list_dashboards	Alle Perses-Dashboard-Definitionen auflisten
create_dashboard	Eine Perses-Dashboard-Definition erstellen oder aktualisieren
delete_dashboard	Eine Dashboard-Definition löschen

Ressourcen & Prompts

• Ressourcen: Tabellen über greptime://<table>/data-URIs durchsuchen
• Prompts: Eingebaute Jinja-Vorlagen für häufige Aufgaben – pipeline_creator, log_pipeline, metrics_analysis, promql_analysis, trace_analysis, table_operation, schema_design_advisor, observability_correlation, ingestion_troubleshooting, query_performance_tuning

Für LLM-Integration und Prompt-Nutzung siehe docs/llm-instructions.md.

Diese Tools decken das Abfragen und Verwalten von Daten in einer bestehenden GreptimeDB ab. Für Bereitstellung, Serverkonfiguration, Schreibprotokolle, Pipeline-Syntax, Schema-Design und Leistungsdiagnose verweisen Sie den Assistenten auf den GreptimeDB-Skills-Index unter https://docs.greptime.com/SKILL.md.

Konfiguration

Umgebungsvariablen

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)

CLI-Argumente

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

HTTP-Servermodus

Für containerisierte oder Kubernetes-Bereitstellungen:

# 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

DNS-Rebinding-Schutz

Standardmäßig ist der DNS-Rebinding-Schutz deaktiviert, um Kompatibilität mit Proxys, Gateways und Kubernetes-Diensten zu gewährleisten. Zum Aktivieren verwenden Sie --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

Wenn Sie auf 421 Invalid Host Header-Fehler stoßen, deaktivieren Sie den Schutz (Standard) oder fügen Sie Ihren Host zur Zulassungsliste hinzu.

Sicherheit

Read-Only-Datenbankbenutzer (empfohlen)

Erstellen Sie einen Read-Only-Benutzer in GreptimeDB mit dem statischen Benutzeranbieter:

mcp_readonly:readonly=your_secure_password

Sicherheitsgate auf Anwendungsebene

Alle Abfragen durchlaufen ein Sicherheitsgate, das:

• blockiert: DROP, DELETE, TRUNCATE, UPDATE, INSERT, ALTER, CREATE, GRANT, REVOKE, EXEC, LOAD, COPY
• blockiert: Kodierte Umgehungsversuche (hex, UNHEX, CHAR)
• erlaubt: SELECT, SHOW, DESCRIBE, TQL, EXPLAIN, UNION

Schreibmodus (standardmäßig deaktiviert)

Der Server ist standardmäßig schreibgeschützt. Der Schreibmodus aktiviert jede Operation, die den gespeicherten Zustand ändert:

• destruktives SQL (DDL/DML wie CREATE, DROP, ALTER, INSERT, UPDATE, DELETE) über 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

Wenn aktiviert, wird das Sicherheitsgate für execute_sql umgangen, und der Server protokolliert beim Start eine Warnung. Bei deaktiviertem Schreibmodus geben diese vier Tools einen Fehler zurück, ohne den Server zu kontaktieren; list_pipelines, list_dashboards und dryrun_pipeline sind schreibgeschützt und bleiben verfügbar.

⚠️ Gefahr: Dies ermöglicht einem KI-Assistenten, destruktive Anweisungen gegen Ihre Datenbank auszuführen. Aktivieren Sie dies niemals gegen Produktionsdaten. Kombinieren Sie es mit einem Read-Only-Datenbankbenutzer, wenn Sie nur Lesezugriff benötigen.

Datenmaskierung

Sensible Spalten werden automatisch maskiert (******) basierend auf Spaltennamenmustern:

• Authentifizierung: password, secret, token, api_key, credential
• Finanzen: credit_card, cvv, bank_account
• Persönlich: ssn, id_card, passport

Konfigurieren Sie mit --mask-patterns phone,email, um benutzerdefinierte Muster hinzuzufügen.

Audit-Protokollierung

Alle Tool-Aufrufe werden protokolliert:

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

Deaktivieren mit --audit-enabled false.

Entwicklung

# 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

Lizenz

MIT-Lizenz – siehe LICENSE.md.

Danksagung

Inspiriert von:

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