Présentation détaillée du projet de serveur ClickHouse MCP

Aperçu

Le serveur ClickHouse MCP est une implémentation du Model Context Protocol (MCP) développée par l'équipe officielle de ClickHouse, spécialement conçue pour fournir aux assistants IA (comme Claude) une connexion sécurisée et des capacités d'interaction avec les bases de données ClickHouse. Ce projet, grâce au protocole MCP standardisé, permet aux assistants IA d'exécuter des requêtes SQL, de gérer la structure des bases de données et d'effectuer des analyses de données en temps réel.

MCP (Model Context Protocol) est une norme ouverte visant à fournir aux applications d'IA une méthode d'intégration de services externes sécurisée et standardisée. Grâce à ce serveur, les utilisateurs peuvent permettre à leurs assistants IA d'accéder directement à leurs bases de données ClickHouse, réalisant ainsi des requêtes et des analyses de données intelligentes.

Fonctionnalités principales

1. Exécution de requêtes SQL (run_select_query)

• Description de la fonctionnalité: Exécute des requêtes SQL sur un cluster ClickHouse.
• Mécanisme de sécurité: Toutes les requêtes sont exécutées en mode readonly = 1, garantissant la sécurité des données.
• Paramètres d'entrée:
  • sql (chaîne de caractères): La requête SQL à exécuter.
• Cas d'utilisation: Extraction de données, analyse statistique, génération de rapports.

2. Gestion des bases de données (list_databases)

• Description de la fonctionnalité: Liste toutes les bases de données dans un cluster ClickHouse.
• Objectif: Exploration de la structure de la base de données, validation des autorisations.
• Contenu renvoyé: Liste des bases de données accessibles.

3. Gestion des tables (list_tables)

• Description de la fonctionnalité: Liste toutes les tables dans une base de données spécifiée.
• Paramètres d'entrée:
  • database (chaîne de caractères): Nom de la base de données.
• Objectif: Exploration de la structure des tables, compréhension du modèle de données.

Configuration et déploiement

Intégration avec Claude Desktop

Chemin de configuration macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Chemin de configuration Windows

%APPDATA%/Claude/claude_desktop_config.json

Exemple de configuration de base

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.13",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<nom-d'hôte-clickhouse>",
        "CLICKHOUSE_PORT": "<port-clickhouse>",
        "CLICKHOUSE_USER": "<nom-d'utilisateur-clickhouse>",
        "CLICKHOUSE_PASSWORD": "<mot-de-passe-clickhouse>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

Configuration des variables d'environnement

Variables obligatoires

• CLICKHOUSE_HOST: Nom d'hôte du serveur ClickHouse.
• CLICKHOUSE_USER: Nom d'utilisateur pour l'authentification.
• CLICKHOUSE_PASSWORD: Mot de passe pour l'authentification.

Variables optionnelles

• CLICKHOUSE_PORT: Numéro de port.
  • Par défaut: 8443 si HTTPS est activé, 8123 si désactivé.
• CLICKHOUSE_SECURE: Active/désactive la connexion HTTPS.
  • Par défaut: "true"
• CLICKHOUSE_VERIFY: Active/désactive la validation du certificat SSL.
  • Par défaut: "true"
• CLICKHOUSE_CONNECT_TIMEOUT: Délai d'attente de connexion (en secondes).
  • Par défaut: "30"
• CLICKHOUSE_SEND_RECEIVE_TIMEOUT: Délai d'attente d'envoi/réception (en secondes).
  • Par défaut: "300"
• CLICKHOUSE_DATABASE: Base de données par défaut à laquelle se connecter.
  • Par défaut: Aucune (utilise la valeur par défaut du serveur).

Cas d'utilisation

1. Configuration de l'environnement de test SQL ClickHouse

{
  "env": {
    "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
    "CLICKHOUSE_PORT": "8443",
    "CLICKHOUSE_USER": "demo",
    "CLICKHOUSE_PASSWORD": "",
    "CLICKHOUSE_SECURE": "true",
    "CLICKHOUSE_VERIFY": "true"
  }
}

2. Configuration de l'environnement de développement local

# Configuration du fichier .env
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_SECURE=false
CLICKHOUSE_VERIFY=false

3. Configuration de ClickHouse Cloud

CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password
# Utiliser les paramètres de sécurité par défaut

Développement et tests

Préparation de l'environnement

# Installation des dépendances
uv sync

# Activation de l'environnement virtuel
source .venv/bin/activate

# Démarrage du serveur de développement
mcp dev mcp_clickhouse/mcp_server.py

Processus de test

# Installation des dépendances de développement
uv sync --all-extras --dev

# Vérification du code
uv run ruff check .

# Démarrage des services de test
docker compose up -d test_services

# Exécution des tests
uv run pytest tests

Considérations de sécurité

Gestion des permissions de la base de données

• Principe du moindre privilège: L'utilisateur de la base de données MCP ne doit avoir que les permissions minimales nécessaires.
• Éviter les comptes administrateur: Il est strictement interdit d'utiliser les utilisateurs par défaut ou administrateur.
• Mode lecture seule: Toutes les requêtes sont exécutées en mode lecture seule, empêchant la modification des données.

Sécurité du réseau

• Connexion HTTPS: Il est recommandé d'activer HTTPS en environnement de production.
• Validation du certificat: Activer la validation du certificat SSL pour assurer la sécurité de la connexion.
• Configuration des délais d'attente: Configurer des délais d'attente de connexion et de requête raisonnables pour éviter l'occupation des ressources.

Caractéristiques techniques

Compatibilité

• Version de Python: Supporte Python 3.13.
• Gestion des dépendances: Utilise uv pour la gestion des paquets.
• Conteneurisation: Supporte le déploiement Docker.
• Multiplateforme: Supporte macOS, Windows, Linux.

Optimisation des performances

• Pool de connexions: Gestion efficace des connexions à la base de données.
• Contrôle des délais d'attente: Délais d'attente de connexion et de requête configurables.
• Support asynchrone: Supporte l'exécution asynchrone des requêtes.

Conclusion

Le projet de serveur ClickHouse MCP constitue un pont sécurisé et efficace entre les assistants IA et les bases de données ClickHouse. Grâce au protocole MCP standardisé, il permet aux assistants IA de comprendre et de manipuler des structures de base de données complexes, d'exécuter des requêtes SQL sophistiquées et de fournir des informations en temps réel sur les données.

Principaux avantages

1. Support officiel: Maintenu par l'équipe officielle de ClickHouse, assurant la compatibilité et la stabilité.
2. Conception sécurisée: Mode lecture seule intégré et contrôle des permissions, protégeant la sécurité des données.
3. Intégration facile: Protocole MCP standardisé, simplifiant l'intégration des applications d'IA.
4. Configuration flexible: Supporte de nombreux scénarios de déploiement, du développement local à la production dans le cloud.
5. Facile à développer: Chaîne d'outils de développement complète et cadre de test.

Scénarios d'application

• Analyse de données: Permettre aux assistants IA d'aider à effectuer des tâches complexes d'analyse de données.
• Business Intelligence: Automatisation de la génération de rapports et des informations sur les données.
• Surveillance en temps réel: Combinaison de l'IA pour la surveillance des indicateurs système et métier.
• Exploration des données: Exploration de la structure et du contenu de la base de données via des requêtes en langage naturel.

Ce projet représente une nouvelle direction dans l'intégration de l'IA et des bases de données, offrant aux développeurs un outil puissant et sécurisé permettant aux assistants IA de réellement comprendre et manipuler les ressources de données d'entreprise.