GreptimeDB

greptimedb-mcp-server

Un serveur Model Context Protocol (MCP) pour GreptimeDB — une base de données d'observabilité open source qui gère les métriques, les journaux et les traces dans un seul moteur.

Permet aux assistants IA d'interroger et d'analyser GreptimeDB à l'aide de requêtes SQL, TQL (compatible PromQL) et RANGE, avec des fonctionnalités de sécurité intégrées comme l'application de la lecture seule et le masquage des données.

Démarrage rapide

# Install
pip install greptimedb-mcp-server

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

Pour Claude Desktop, ajoutez ceci à votre configuration (~/Library/Application Support/Claude/claude_desktop_config.json sur macOS) :

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

Fonctionnalités

Outils

Outil	Description
execute_sql	Exécute des requêtes SQL avec des options de format (csv/json/markdown) et de limite
execute_tql	Exécute des requêtes TQL (compatible PromQL) pour l'analyse de séries temporelles
query_range	Exécute des requêtes d'agrégation par fenêtre temporelle avec la syntaxe RANGE/ALIGN
search_table_semantics	Trouve des tables par concept d'observabilité, classées par termes correspondants ; recherche les noms de tables, les options sémantiques et les déclarations d'entités. schema sélectionne la base de données à rechercher
query_semantic_graph	Interroge le graphe sémantique : summary (ce qu'il contient), entities (nœuds), relationships (arêtes) sur une fenêtre temporelle requise
describe_table	Inspecte un profil de table : schéma, métadonnées sémantiques, dernières lignes d'échantillon et conseils de requête
explain_query	Analyse les plans d'exécution de requêtes SQL ou TQL (analyze=true pour les statistiques d'exécution ; ajoutez verbose=true avec analyze=true pour les métriques de scan par partition et les compteurs de pruning d'index)
health_check	Vérifie l'état de la connexion à la base de données et la version du serveur

search_table_semantics et les métadonnées sémantiques dans describe_table lisent information_schema.table_semantics. Une table y apparaît lorsqu'elle porte une option greptime.semantic.* ou qu'une convention intégrée en dérive une déclaration d'entité ; les autres tables sont absentes. Le serveur lit la liste des colonnes de la vue une fois par processus et ne sélectionne que les colonnes qu'il expose. entity_declarations nécessite GreptimeDB 1.3 ; sur les versions antérieures, il est signalé comme une colonne manquante plutôt que comme un ensemble de déclarations vide.

Les résultats des outils sont limités par GREPTIMEDB_MAX_RESULT_BYTES (par défaut 1048576, soit 1 Mio). Un résultat de requête dépassant le budget renvoie moins de lignes et le signale dans truncated et truncation_reason ; un résultat sans lignes à retirer est tronqué avec un avis à la fin. Le budget est un filet de sécurité contre un résultat trop volumineux pour être consommé, alors abaissez-le si votre client MCP rejette les résultats avant qu'il ne soit atteint.

Requêtes inter-bases de données

Le serveur se connecte à une base de données, mais les lectures ne sont pas limitées à celle-ci :

Outil	Comment atteindre une autre base de données
execute_sql, query_range, describe_table	Qualifiez la table comme schema.table
execute_tql	metric{__schema__="other_db"}, qui n'accepte que =
search_table_semantics	Passez schema
query_semantic_graph	Déjà à l'échelle du catalogue ; aucun cadrage nécessaire

Le compte connecté doit avoir la permission de lecture sur la base de données cible. Utilisez SHOW DATABASES pour les lister.

query_semantic_graph lit greptime_private.semantic_entities et greptime_private.semantic_relationships, qui nécessitent GreptimeDB 1.3. Au démarrage, le serveur vérifie que les deux vues existent, portent les colonnes qu'il lit et sont lisibles par le compte connecté ; si ce n'est pas le cas, l'outil n'est pas proposé et la raison est journalisée. Sa fenêtre temporelle est requise et semi-ouverte, [start_time, end_time) sur observed_at, et les lignes sont agrégées sur les compartiments d'observation de 60 secondes dans cette fenêtre.

Gestion des pipelines

Outil	Description
list_pipelines	Liste tous les pipelines ou obtient les détails d'un pipeline spécifique
create_pipeline	Crée un nouveau pipeline avec une configuration YAML
dryrun_pipeline	Teste un pipeline avec des données d'échantillon sans écrire dans la base de données
delete_pipeline	Supprime une version spécifique d'un pipeline

Gestion des tableaux de bord

Outil	Description
list_dashboards	Liste toutes les définitions de tableaux de bord Perses
create_dashboard	Crée ou met à jour une définition de tableau de bord Perses
delete_dashboard	Supprime une définition de tableau de bord

Ressources et invites

• Ressources : Parcourez les tables via les URI greptime://<table>/data
• Invites : Modèles Jinja intégrés pour les tâches courantes — pipeline_creator, log_pipeline, metrics_analysis, promql_analysis, trace_analysis, table_operation, schema_design_advisor, observability_correlation, ingestion_troubleshooting, query_performance_tuning

Pour l'intégration LLM et l'utilisation des invites, consultez docs/llm-instructions.md.

Ces outils couvrent l'interrogation et la gestion des données dans une GreptimeDB existante. Pour le déploiement, la configuration du serveur, les protocoles d'écriture, la syntaxe des pipelines, la conception des schémas et le diagnostic des performances, orientez l'assistant vers l'index des compétences GreptimeDB à https://docs.greptime.com/SKILL.md.

Configuration

Variables d'environnement

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)

Arguments 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

Mode serveur HTTP

Pour les déploiements conteneurisés ou 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

Protection contre le rebinding DNS

Par défaut, la protection contre le rebinding DNS est désactivée pour la compatibilité avec les proxys, les passerelles et les services Kubernetes. Pour l'activer, utilisez --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 vous rencontrez des erreurs 421 Invalid Host Header, désactivez la protection (par défaut) ou ajoutez votre hôte à la liste autorisée.

Sécurité

Utilisateur de base de données en lecture seule (recommandé)

Créez un utilisateur en lecture seule dans GreptimeDB à l'aide du fournisseur d'utilisateurs statique :

mcp_readonly:readonly=your_secure_password

Passerelle de sécurité au niveau de l'application

Toutes les requêtes passent par une passerelle de sécurité qui :

• Bloque : DROP, DELETE, TRUNCATE, UPDATE, INSERT, ALTER, CREATE, GRANT, REVOKE, EXEC, LOAD, COPY
• Bloque : Tentatives de contournement encodées (hex, UNHEX, CHAR)
• Autorise : SELECT, SHOW, DESCRIBE, TQL, EXPLAIN, UNION

Mode écriture (désactivé par défaut)

Le serveur est en lecture seule par défaut. Le mode écriture active chaque opération qui modifie l'état stocké :

• SQL destructif (DDL/DML tel que CREATE, DROP, ALTER, INSERT, UPDATE, DELETE) via 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

Lorsqu'il est activé, la passerelle de sécurité est contournée pour execute_sql, et le serveur journalise un avertissement au démarrage. Avec le mode écriture désactivé, ces quatre outils renvoient une erreur sans contacter le serveur ; list_pipelines, list_dashboards et dryrun_pipeline sont en lecture seule et restent disponibles.

⚠️ Danger : Cela permet à un assistant IA d'exécuter des instructions destructives contre votre base de données. Ne l'activez jamais sur des données de production. Combinez-le avec un utilisateur de base de données en lecture seule si vous n'avez besoin que d'un accès en lecture.

Masquage des données

Les colonnes sensibles sont automatiquement masquées (******) en fonction des modèles de noms de colonnes :

• Authentification : password, secret, token, api_key, credential
• Financier : credit_card, cvv, bank_account
• Personnel : ssn, id_card, passport

Configurez avec --mask-patterns phone,email pour ajouter des modèles personnalisés.

Journalisation d'audit

Toutes les invocations d'outils sont journalisées :

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

Désactivez avec --audit-enabled false.

Développement

# 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

Licence

Licence MIT - voir LICENSE.md.

Remerciements

Inspiré par :

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