GreptimeDB MCP Server

officiel

Fournit aux assistants IA un moyen sécurisé et structuré d'explorer et d'analyser les données dans GreptimeDB.

Documentation

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 logs et les traces dans un seul moteur.

Permet aux assistants IA d'interroger et d'analyser GreptimeDB en utilisant des requêtes SQL, TQL (compatible PromQL) et RANGE, avec des fonctionnalités de sécurité intégrées telles que l'application du mode 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écuter des requêtes SQL avec des options de format (csv/json/markdown) et de limite
`execute_tql`	Exécuter des requêtes TQL (compatible PromQL) pour l'analyse de séries temporelles
`query_range`	Exécuter des requêtes d'agrégation par fenêtre temporelle avec la syntaxe RANGE/ALIGN
`describe_table`	Inspecter le profil d'une table : schéma, métadonnées sémantiques, derniers échantillons de lignes et conseils de requête
`explain_query`	Analyser les plans d'exécution des 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érifier l'état de la connexion à la base de données et la version du serveur

Gestion des pipelines

Outil	Description
`list_pipelines`	Lister tous les pipelines ou obtenir les détails d'un pipeline spécifique
`create_pipeline`	Créer un nouveau pipeline avec une configuration YAML
`dryrun_pipeline`	Tester un pipeline avec des données d'exemple sans écrire dans la base de données
`delete_pipeline`	Supprimer une version spécifique d'un pipeline

Gestion des tableaux de bord

Outil	Description
`list_dashboards`	Lister toutes les définitions de tableaux de bord Perses
`create_dashboard`	Créer ou mettre à jour une définition de tableau de bord Perses
`delete_dashboard`	Supprimer 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, consultez docs/llm-instructions.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 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. Nécessite 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

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 en utilisant le fournisseur d'utilisateurs statique :

mcp_readonly:readonly=your_secure_password

Barrière de sécurité au niveau applicatif

Toutes les requêtes passent par une barrière de sécurité qui :

Bloque : DROP, DELETE, TRUNCATE, UPDATE, INSERT, ALTER, CREATE, GRANT, REVOKE, EXEC, LOAD, COPY
Bloque : Les 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 les écritures/SQL destructrices (DDL/DML telles 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 barrière de sécurité est contournée pour execute_sql, et le serveur enregistre un avertissement au démarrage.

⚠️ Danger : Cela permet à un assistant IA d'exécuter des instructions destructrices sur votre base de données. Ne l'activez jamais sur des données de production. Combinez 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 motifs 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 motifs 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 :