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 en utilisant SQL, TQL (compatible PromQL) et les requêtes 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 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
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 le profil d'une table : schéma, métadonnées sémantiques, derniers échantillons de lignes 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 d'élagage 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.

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, contiennent les colonnes qu'il lit et sont lisibles par le compte connecté ; lorsqu'elles ne le sont pas, l'outil n'est pas proposé et la raison est consignée dans les journaux. 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'exemple 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 : Parcourir 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, voir docs/llm-instructions.md.

Ces outils couvrent l'interrogation et la gestion des données dans une instance 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 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)

Arguments de ligne de commande

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 la rebinding DNS

Par défaut, la protection contre la 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 en utilisant le 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. Pour le développement local ou les tests, vous pouvez autoriser le SQL d'écriture/destructif (DDL/DML tel que CREATE, DROP, ALTER, INSERT, UPDATE, DELETE) via l'outil execute_sql en activant le mode écriture :

# 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 consigne un avertissement au démarrage.

⚠️ 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