GreptimeDB MCP Server

offiziell

Bietet KI-Assistenten eine sichere und strukturierte Möglichkeit, Daten in GreptimeDB zu erkunden und zu analysieren.

GitHub
27

Dokumentation

greptimedb-mcp-server

PyPI - Version build workflow MCP Registry MIT License

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 die Abfrage und Analyse von GreptimeDB mittels SQL, TQL (PromQL-kompatibel) und RANGE-Abfragen, 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

Werkzeuge

WerkzeugBeschreibung
execute_sqlSQL-Abfragen mit Format- (csv/json/markdown) und Limit-Optionen ausführen
execute_tqlTQL (PromQL-kompatible) Abfragen für Zeitreihenanalysen ausführen
query_rangeZeitfenster-Aggregationsabfragen mit RANGE/ALIGN-Syntax ausführen
describe_tableEin Tabellenprofil untersuchen: Schema, semantische Metadaten, neueste Beispielzeilen und Abfragehinweise
explain_queryAusführungspläne von SQL- oder TQL-Abfragen analysieren (analyze=true für Laufzeitstatistiken; fügen Sie verbose=true zusammen mit analyze=true hinzu, um partitionsbezogene Scan-Metriken und Index-Pruning-Zähler zu erhalten)
health_checkDatenbankverbindungsstatus und Serverversion prüfen

Pipeline-Verwaltung

WerkzeugBeschreibung
list_pipelinesAlle Pipelines auflisten oder Details einer bestimmten Pipeline abrufen
create_pipelineEine neue Pipeline mit YAML-Konfiguration erstellen
dryrun_pipelineEine Pipeline mit Beispieldaten testen, ohne in die Datenbank zu schreiben
delete_pipelineEine bestimmte Version einer Pipeline löschen

Dashboard-Verwaltung

WerkzeugBeschreibung
list_dashboardsAlle Perses-Dashboard-Definitionen auflisten
create_dashboardEine Perses-Dashboard-Definition erstellen oder aktualisieren
delete_dashboardEine Dashboard-Definition löschen

Ressourcen & Prompts

  • Ressourcen: Tabellen über greptime://<table>/data-URIs durchsuchen
  • Prompts: Integrierte 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.

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 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)

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-Server-Modus

Für containerisierte oder Kubernetes-Bereitstellungen. Erfordert 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

DNS-Rebinding-Schutz

Standardmäßig ist der DNS-Rebinding-Schutz deaktiviert, um Kompatibilität mit Proxys, Gateways und Kubernetes-Diensten zu gewährleisten. Um ihn zu 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 entweder den Schutz (Standard) oder fügen Sie Ihren Host zur Erlaubnisliste hinzu.

Sicherheit

Read-Only-Datenbankbenutzer (Empfohlen)

Erstellen Sie einen schreibgeschützten Benutzer in GreptimeDB mit dem Static User Provider:

mcp_readonly:readonly=your_secure_password

Sicherheitsschleuse auf Anwendungsebene

Alle Abfragen durchlaufen eine Sicherheitsschleuse, die:

  • Blockiert: DROP, DELETE, TRUNCATE, UPDATE, INSERT, ALTER, CREATE, GRANT, REVOKE, EXEC, LOAD, COPY
  • Blockiert: Verschlüsselte Umgehungsversuche (hex, UNHEX, CHAR)
  • Erlaubt: SELECT, SHOW, DESCRIBE, TQL, EXPLAIN, UNION

Schreibmodus (Standardmäßig deaktiviert)

Der Server ist standardmäßig schreibgeschützt. Für lokale Entwicklung oder Tests können Sie schreibende/destruktive SQL-Befehle (DDL/DML wie CREATE, DROP, ALTER, INSERT, UPDATE, DELETE) über das execute_sql-Werkzeug zulassen, indem Sie den Schreibmodus aktivieren:

# Environment variable
GREPTIMEDB_ALLOW_WRITE=true greptimedb-mcp-server

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

Wenn aktiviert, wird die Sicherheitsschleuse für execute_sql umgangen, und der Server protokolliert eine Warnung beim Start.

⚠️ Gefahr: Dies erlaubt einem KI-Assistenten, destruktive Anweisungen gegen Ihre Datenbank auszuführen. Aktivieren Sie dies niemals für Produktionsdaten. Kombinieren Sie es mit einem schreibgeschützten 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 Werkzeugaufrufe 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: