ClickHouse

Serveur MCP ClickHouse

Un serveur MCP pour ClickHouse.

Fonctionnalités

Outils ClickHouse

• run_query

  • Exécutez des requêtes SQL sur votre cluster ClickHouse.
  • Entrée : query (chaîne) : La requête SQL à exécuter.
  • Les requêtes s'exécutent en mode lecture seule par défaut (CLICKHOUSE_ALLOW_WRITE_ACCESS=false), mais les écritures peuvent être activées explicitement si nécessaire.

• list_databases

  • Listez toutes les bases de données de votre cluster ClickHouse.

• list_tables

  • Listez les tables d'une base de données avec pagination.
  • Entrée obligatoire : database (chaîne).
  • Entrées facultatives :
    • like / not_like (chaîne) : Appliquez des filtres LIKE ou NOT LIKE aux noms de tables.
    • page_token (chaîne) : Jeton retourné par un appel précédent pour récupérer la page suivante.
    • page_size (entier, par défaut 50) : Nombre de tables retournées par page.
    • include_detailed_columns (booléen, par défaut true) : Lorsque false, omet les métadonnées des colonnes pour des réponses plus légères tout en conservant le create_table_query complet.
  • Forme de la réponse :
    • tables : Tableau d'objets table pour la page actuelle.
    • next_page_token : Transmettez cette valeur pour récupérer la page suivante, ou null lorsqu'il n'y a plus de tables.
    • total_tables : Nombre total de tables correspondant aux filtres fournis.

Outils chDB

• run_chdb_select_query
  • Exécutez des requêtes SQL en utilisant le moteur ClickHouse embarqué de chDB.
  • Entrée : query (chaîne) : La requête SQL à exécuter.
  • Interrogez les données directement depuis diverses sources (fichiers, URL, bases de données) sans processus ETL.
  • Nécessite l'extra optionnel chdb : pip install 'mcp-clickhouse[chdb]'

Point de terminaison de vérification de santé

Lors de l'exécution avec le transport HTTP ou SSE, un point de terminaison de vérification de santé est disponible à /health. Ce point de terminaison :

• Retourne 200 OK (corps : OK) si le serveur est sain et peut se connecter à ClickHouse
• Retourne 503 Service Unavailable avec un message d'erreur générique si le serveur ne peut pas se connecter à ClickHouse

Le point de terminaison est intentionnellement non authentifié afin que les sondes d'orchestration (par exemple, les sondes de vivacité/préparation Kubernetes, les équilibreurs de charge) puissent y accéder sans informations d'identification. Le corps de la réponse est délibérément minimal pour éviter de divulguer les versions du backend ou les détails des erreurs ; déboguez les échecs via les journaux du serveur.

Exemple :

curl http://localhost:8000/health
# Response: OK

Sécurité

Authentification pour les transports HTTP/SSE

Lors de l'utilisation du transport HTTP ou SSE, l'authentification est requise par défaut. Le transport stdio (par défaut) ne nécessite pas d'authentification car il communique uniquement via l'entrée/sortie standard.

Trois modes d'authentification sont pris en charge. Choisissez-en un :

Mode	Quand l'utiliser	Variable d'environnement
Jeton porteur statique	Déploiements simples, services internes	CLICKHOUSE_MCP_AUTH_TOKEN
OAuth / OIDC (via FastMCP)	Azure Entra, Google, GitHub, WorkOS, etc.	FASTMCP_SERVER_AUTH=<provider-class-path> (+ variables FASTMCP_SERVER_AUTH_* spécifiques au fournisseur)
Désactivé	Développement local uniquement	CLICKHOUSE_MCP_AUTH_DISABLED=true

Le démarrage échoue si aucun de ces éléments n'est configuré pour les transports HTTP/SSE.

Configuration de l'authentification

1. Générez un jeton sécurisé (peut être n'importe quelle chaîne aléatoire) :

   # Using uuidgen (macOS/Linux)
   uuidgen
   
   # Using openssl
   openssl rand -hex 32
   

2. Configurez le serveur avec le jeton :

   export CLICKHOUSE_MCP_AUTH_TOKEN="your-generated-token"
   

3. Configurez votre client MCP pour inclure le jeton dans les requêtes :

   Pour Claude Desktop avec le transport HTTP/SSE :

   {
     "mcpServers": {
       "mcp-clickhouse": {
         "url": "http://127.0.0.1:8000",
         "headers": {
           "Authorization": "Bearer your-generated-token"
         }
       }
     }
   }
   

   Remarque : le point de terminaison /health est intentionnellement non authentifié (voir Point de terminaison de vérification de santé ci-dessus). Pour vérifier que l'authentification par jeton porteur rejette effectivement les requêtes non authentifiées, interrogez le point de terminaison MCP lui-même, par exemple avec l'inspecteur MCP, ou en envoyant une requête JSON-RPC par POST à /mcp avec et sans l'en-tête Authorization et en confirmant que l'appel non authentifié retourne 401.

OAuth / OIDC via FastMCP

Pour les déploiements en production avec des fournisseurs d'identité (Azure Entra, Google, GitHub, WorkOS, etc.), déléguez l'authentification aux fournisseurs d'authentification intégrés de FastMCP au lieu d'utiliser un jeton statique. Définissez FASTMCP_SERVER_AUTH sur le chemin complet de la classe d'un fournisseur d'authentification FastMCP, ainsi que les variables FASTMCP_SERVER_AUTH_* spécifiques au fournisseur, et laissez CLICKHOUSE_MCP_AUTH_TOKEN non défini.

Exemple (Azure Entra) :

export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.azure.AzureProvider
export FASTMCP_SERVER_AUTH_AZURE_TENANT_ID="<tenant-id>"
export FASTMCP_SERVER_AUTH_AZURE_CLIENT_ID="<client-id>"
export FASTMCP_SERVER_AUTH_AZURE_CLIENT_SECRET="<client-secret>"

Consultez la documentation FastMCP pour la liste complète des fournisseurs et leurs variables d'environnement requises.

Mode développement (Désactiver l'authentification)

Pour le développement et les tests locaux uniquement, vous pouvez désactiver l'authentification en définissant :

export CLICKHOUSE_MCP_AUTH_DISABLED=true

AVERTISSEMENT : Utilisez ceci uniquement pour le développement local. Ne désactivez pas l'authentification lorsque le serveur est exposé à un réseau quelconque.

Configuration

Ce serveur MCP prend en charge à la fois ClickHouse et chDB. Vous pouvez activer l'un ou les deux selon vos besoins.

1. Ouvrez le fichier de configuration de Claude Desktop situé à :

   • Sur macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
   • Sur Windows : %APPDATA%/Claude/claude_desktop_config.json

2. Ajoutez ce qui suit :

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_ROLE": "<clickhouse-role>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

Mettez à jour les variables d'environnement pour pointer vers votre propre service ClickHouse.

Ou, si vous souhaitez l'essayer avec le ClickHouse SQL Playground, vous pouvez utiliser la configuration suivante :

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

Pour chDB (moteur ClickHouse embarqué), ajoutez la configuration suivante :

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse[chdb]",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CHDB_ENABLED": "true",
        "CLICKHOUSE_ENABLED": "false",
        "CHDB_DATA_PATH": "/path/to/chdb/data"
      }
    }
  }
}

Vous pouvez également activer ClickHouse et chDB simultanément :

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse[chdb]",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30",
        "CHDB_ENABLED": "true",
        "CHDB_DATA_PATH": "/path/to/chdb/data"
      }
    }
  }
}

3. Localisez l'entrée de commande pour uv et remplacez-la par le chemin absolu vers l'exécutable uv. Cela garantit que la version correcte de uv est utilisée lors du démarrage du serveur. Sur un mac, vous pouvez trouver ce chemin en utilisant which uv.

4. Redémarrez Claude Desktop pour appliquer les modifications.

Accès en écriture facultatif

Par défaut, ce MCP applique des requêtes en lecture seule afin que des mutations accidentelles ne puissent pas se produire pendant l'exploration. Pour autoriser les instructions DDL ou INSERT/UPDATE, définissez la variable d'environnement CLICKHOUSE_ALLOW_WRITE_ACCESS sur true. Le serveur continue d'appliquer le mode lecture seule si l'instance ClickHouse elle-même interdit les écritures.

Protection contre les opérations destructrices

Même lorsque l'accès en écriture est activé (CLICKHOUSE_ALLOW_WRITE_ACCESS=true), les opérations destructrices (DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE) nécessitent un indicateur d'adhésion supplémentaire pour des raisons de sécurité. Cela empêche la suppression accidentelle de données pendant l'exploration par l'IA.

Pour activer les opérations destructrices, définissez les deux indicateurs :

"env": {
  "CLICKHOUSE_ALLOW_WRITE_ACCESS": "true",
  "CLICKHOUSE_ALLOW_DROP": "true"
}

Cette approche à deux niveaux garantit que les suppressions accidentelles sont très difficiles :

• Les opérations d'écriture (INSERT, UPDATE, CREATE) nécessitent CLICKHOUSE_ALLOW_WRITE_ACCESS=true
• Les opérations destructrices (DROP, TRUNCATE) nécessitent en plus CLICKHOUSE_ALLOW_DROP=true

Exécution sans uv (Utilisation de Python système)

Si vous préférez utiliser l'installation Python système au lieu de uv, vous pouvez installer le paquet depuis PyPI et l'exécuter directement :

1. Installez le paquet en utilisant pip :

   python3 -m pip install mcp-clickhouse
   

   Pour installer également le support chDB :

   python3 -m pip install 'mcp-clickhouse[chdb]'
   

   Pour mettre à niveau vers la dernière version :

   python3 -m pip install --upgrade mcp-clickhouse
   

2. Mettez à jour votre configuration Claude Desktop pour utiliser Python directement :

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "python3",
      "args": [
        "-m",
        "mcp_clickhouse.main"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

Alternativement, vous pouvez utiliser le script installé directement :

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "mcp-clickhouse",
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

Remarque : Assurez-vous d'utiliser le chemin complet vers l'exécutable Python ou le script mcp-clickhouse s'ils ne sont pas dans votre PATH système. Vous pouvez trouver les chemins en utilisant :

• which python3 pour l'exécutable Python
• which mcp-clickhouse pour le script installé

Middleware personnalisé

Vous pouvez ajouter un middleware personnalisé au serveur MCP sans modifier le code source. FastMCP fournit un système de middleware qui vous permet d'intercepter et de traiter les messages du protocole MCP (appels d'outils, lectures de ressources, invites, etc.).

Comment l'utiliser

1. Créez un module Python avec des classes de middleware étendant Middleware et une fonction setup_middleware(mcp) :

# my_middleware.py
import logging
from fastmcp.server.middleware import Middleware, MiddlewareContext, CallNext

logger = logging.getLogger("my-middleware")

class LoggingMiddleware(Middleware):
    """Log all tool calls."""
    
    async def on_call_tool(self, context: MiddlewareContext, call_next: CallNext):
        tool_name = context.message.name if hasattr(context.message, 'name') else 'unknown'
        logger.info(f"Calling tool: {tool_name}")
        result = await call_next(context)
        logger.info(f"Tool {tool_name} completed")
        return result

def setup_middleware(mcp):
    """Register middleware with the MCP server."""
    mcp.add_middleware(LoggingMiddleware())

2. Définissez la variable d'environnement MCP_MIDDLEWARE_MODULE sur le nom du module (sans l'extension .py) :

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": ["run", "--with", "mcp-clickhouse", "--python", "3.10", "mcp-clickhouse"],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "MCP_MIDDLEWARE_MODULE": "my_middleware"
      }
    }
  }
}

3. Assurez-vous que votre module de middleware est dans le chemin d'importation de Python (par exemple, dans le même répertoire où le serveur MCP s'exécute, ou installé en tant que paquet).

Exemple de middleware

Un exemple de module de middleware est fourni dans example_middleware.py montrant des modèles courants :

• Journalisation de toutes les requêtes MCP
• Journalisation spécifique des appels d'outils
• Mesure du temps de traitement des requêtes

Pour utiliser l'exemple :

"env": {
  "MCP_MIDDLEWARE_MODULE": "example_middleware"
}

Capacités du middleware

La classe de base Middleware fournit des points d'ancrage pour différentes opérations MCP :

• on_message(context, call_next) - Appelé pour tous les messages
• on_request(context, call_next) - Appelé pour toutes les requêtes
• on_notification(context, call_next) - Appelé pour toutes les notifications
• on_call_tool(context, call_next) - Appelé lorsqu'un outil est exécuté
• on_read_resource(context, call_next) - Appelé lorsqu'une ressource est lue
• on_get_prompt(context, call_next) - Appelé lorsqu'une invite est récupérée
• on_list_tools(context, call_next) - Appelé lors du listage des outils
• on_list_resources(context, call_next) - Appelé lors du listage des ressources
• on_list_resource_templates(context, call_next) - Appelé lors du listage des modèles de ressources
• on_list_prompts(context, call_next) - Appelé lors du listage des invites

Chaque point d'ancrage reçoit un objet MiddlewareContext contenant le message et les métadonnées, et une fonction call_next pour continuer le pipeline.

Configuration dynamique du client via l'état du contexte

Le middleware peut remplacer la configuration du client ClickHouse sur une base par requête en utilisant la clé d'état de contexte CLIENT_CONFIG_OVERRIDES_KEY. Le serveur fusionne ces remplacements avec la configuration de base provenant des variables d'environnement.

from fastmcp.server.dependencies import get_context
from mcp_clickhouse.mcp_server import CLIENT_CONFIG_OVERRIDES_KEY

ctx = get_context()
ctx.set_state(CLIENT_CONFIG_OVERRIDES_KEY, {
    "connect_timeout": 60,
    "send_receive_timeout": 120
})

Cela permet des cas d'utilisation avancés comme les ajustements dynamiques de délai d'attente, le routage spécifique au locataire ou les paramètres de connexion par utilisateur.

Développement

1. Dans le répertoire test-services, exécutez docker compose up -d pour démarrer le cluster ClickHouse.

2. Ajoutez les variables suivantes à un fichier .env à la racine du dépôt.

Remarque : L'utilisation de l'utilisateur default dans ce contexte est destinée uniquement à des fins de développement local.

CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

3. Exécutez uv sync pour installer les dépendances. Pour installer uv, suivez les instructions ici. Ensuite, faites source .venv/bin/activate.

4. Pour des tests faciles avec l'inspecteur MCP, exécutez fastmcp dev mcp_clickhouse/mcp_server.py pour démarrer le serveur MCP.

5. Pour tester avec le transport HTTP et le point de terminaison de vérification de santé :

   # For development, disable authentication
   CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_DISABLED=true python -m mcp_clickhouse.main
   
   # Or with authentication (generate a token first)
   CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_TOKEN="your-token" python -m mcp_clickhouse.main
   
   # Then in another terminal:
   curl http://localhost:8000/health
   

Variables d'environnement

La configuration est divisée en groupes indépendants. Les mélanger est une cause fréquente d'échecs de connexion difficiles à déboguer :

Groupe	Variables	Contrôle
Connexion à la base de données ClickHouse	CLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY, …	Comment ce serveur MCP se connecte à votre cluster ClickHouse via l'interface HTTP
Serveur MCP / transport	CLICKHOUSE_MCP_*, FASTMCP_SERVER_AUTH, FASTMCP_SERVER_AUTH_*	Transport MCP, authentification et limites d'exécution de l'outil de requête
Middleware / chDB	MCP_MIDDLEWARE_MODULE, CHDB_*	Extensions facultatives

[!IMPORTANT] Les variables telles que CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY et CLICKHOUSE_PORT s'appliquent uniquement à la connexion à la base de données ClickHouse. Elles ne configurent pas TLS, les ports ou l'authentification pour le point de terminaison du protocole MCP.

Exemple : si le serveur MCP s'exécute dans Kubernetes derrière une entrée qui termine TLS, c'est une préoccupation de transport MCP. Gardez CLICKHOUSE_SECURE aligné sur la façon dont le pod atteint ClickHouse lui-même (HTTPS → true, HTTP simple → false). Définir CLICKHOUSE_SECURE=false parce que le serveur MCP est derrière une entrée amènera le serveur à composer le numéro vers ClickHouse via HTTP — souvent contre un port HTTPS uniquement — et produira des erreurs HTTP/TLS opaques dans les journaux du serveur.

Connexion à la base de données ClickHouse

Ces variables configurent le client HTTP clickhouse-connect et le comportement des outils adossés à ClickHouse tels que run_query, list_databases et list_tables.

Variables obligatoires

• CLICKHOUSE_HOST : Le nom d'hôte de votre serveur ClickHouse (point de terminaison de la base de données, pas l'adresse de liaison du serveur MCP)
• CLICKHOUSE_USER : Le nom d'utilisateur pour l'authentification ClickHouse
• CLICKHOUSE_PASSWORD : Le mot de passe pour l'authentification ClickHouse

[!CAUTION] Il est important de traiter votre utilisateur de base de données MCP comme n'importe quel client externe se connectant à votre base de données, en ne lui accordant que les privilèges minimaux nécessaires à son fonctionnement. L'utilisation d'utilisateurs par défaut ou administratifs doit être strictement évitée en toutes circonstances.

Variables optionnelles

• CLICKHOUSE_PORT : Port de l'interface HTTP de votre serveur ClickHouse
  • Par défaut : 8443 si CLICKHOUSE_SECURE=true, 8123 si CLICKHOUSE_SECURE=false
  • N'a généralement pas besoin d'être défini, sauf si vous utilisez un port non standard
  • Doit être un port d'interface HTTP, pas le port du protocole TCP natif utilisé par clickhouse-client
  • Valeurs courantes :
    • HTTP : 8123 (clair) / 8443 (TLS) — utilisé par ce serveur et ClickHouse Cloud HTTPS
    • TCP natif (non pris en charge ici) : 9000 (clair) / 9440 (TLS) — utilisé par clickhouse-client
  • Si le serveur répond avec Port 9000 is for clickhouse-client program, vous êtes dirigé vers le protocole natif ; passez au port HTTP (8123/8443 ou le mappage HTTP de votre déploiement)
• CLICKHOUSE_ROLE : Le rôle ClickHouse à utiliser pour l'authentification
  • Par défaut : Aucun
  • Définissez-le si votre utilisateur nécessite un rôle spécifique
• CLICKHOUSE_SECURE : Activer HTTPS pour la connexion à la base de données ClickHouse (pas pour les clients MCP)
  • Par défaut : "true"
  • Mettez à "false" uniquement lorsque le serveur MCP atteint ClickHouse via HTTP simple (typique pour Docker Compose local sur le port 8123)
  • Laissez "true" pour ClickHouse Cloud et tout point de terminaison de base de données HTTPS, même si le serveur MCP lui-même est exposé via HTTP, stdio ou une entrée qui termine TLS séparément
  • Une mauvaise correspondance de ce drapeau avec le port de la base de données (par exemple, CLICKHOUSE_SECURE=false sur le port 8443) est une erreur de configuration fréquente et se manifeste généralement par des erreurs déroutantes du client HTTP plutôt que par un message clair de « mauvais schéma »
• CLICKHOUSE_VERIFY : Activer/désactiver la vérification du certificat SSL pour la connexion HTTPS ClickHouse
  • Par défaut : "true"
  • Mettez à "false" pour désactiver la vérification du certificat (non recommandé en production)
  • Certificats TLS : Le paquet utilise le magasin de confiance de votre système d'exploitation pour la vérification des certificats TLS via truststore. Nous appelons truststore.inject_into_ssl() au démarrage pour garantir une gestion correcte des certificats. Le comportement SSL par défaut de Python est utilisé comme solution de repli uniquement en cas d'erreur inattendue.
• CLICKHOUSE_SERVER_HOST_NAME : Nom d'hôte du serveur pour la substitution SNI et la validation du certificat sur la connexion ClickHouse
  • Par défaut : Aucun (utilise le nom d'hôte de connexion)
  • Ceci est utile lors de la connexion via des proxys ou des équilibreurs de charge où le nom d'hôte du certificat diffère du nom d'hôte de connexion. Lorsqu'il est défini, ce nom d'hôte sera utilisé à la fois pour SNI (Server Name Indication) pendant la poignée de main TLS et pour la validation du nom d'hôte du certificat.
• CLICKHOUSE_PROXY_PATH : Préfixe de chemin d'URL pour le point de terminaison HTTP ClickHouse
  • Par défaut : Aucun
  • Définissez-le lorsque l'interface HTTP ClickHouse est exposée derrière un proxy inverse sous un préfixe de chemin (par exemple, /clickhouse)
• CLICKHOUSE_CONNECT_TIMEOUT : Délai de connexion en secondes pour le client ClickHouse
  • Par défaut : "30"
  • Augmentez cette valeur si vous rencontrez des délais de connexion
• CLICKHOUSE_SEND_RECEIVE_TIMEOUT : Délai d'envoi/réception en secondes pour le client ClickHouse
  • Par défaut : "300"
  • Augmentez cette valeur pour les requêtes de longue durée
• CLICKHOUSE_DATABASE : Base de données ClickHouse par défaut à utiliser
  • Par défaut : Aucune (utilise la valeur par défaut du serveur)
  • Définissez-la pour vous connecter automatiquement à une base de données spécifique
• CLICKHOUSE_ENABLED : Activer/désactiver les outils de base de données ClickHouse
  • Par défaut : "true"
  • Mettez à "false" pour désactiver les outils ClickHouse lors de l'utilisation de chDB uniquement
• CLICKHOUSE_ALLOW_WRITE_ACCESS : Autoriser les opérations d'écriture (DDL et DML) sur ClickHouse
  • Par défaut : "false"
  • Mettez à "true" pour autoriser les opérations DDL (CREATE, ALTER, DROP) et DML (INSERT, UPDATE, DELETE)
  • Lorsqu'il est désactivé (par défaut), les requêtes s'exécutent avec le paramètre readonly=1 pour empêcher les modifications de données
• CLICKHOUSE_ALLOW_DROP : Autoriser les opérations destructrices (DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE)
  • Par défaut : "false"
  • Ne prend effet que lorsque CLICKHOUSE_ALLOW_WRITE_ACCESS=true est également défini
  • Mettez à "true" pour autoriser explicitement les opérations destructrices DROP et TRUNCATE
  • Il s'agit d'une fonction de sécurité pour empêcher la suppression accidentelle de données lors de l'exploration par IA

Serveur MCP et transport

Ces variables contrôlent le processus MCP lui-même, y compris le transport, l'authentification et les limites d'exécution des outils de requête. Elles sont indépendantes des paramètres de la base de données ClickHouse ci-dessus. Voir aussi Authentification pour les transports HTTP/SSE.

• CLICKHOUSE_MCP_SERVER_TRANSPORT : Définit la méthode de transport pour le serveur MCP
  • Par défaut : "stdio"
  • Options valides : "stdio", "http", "sse". Ceci est utile pour le développement local avec des outils comme MCP Inspector.
  • stdio est typique pour Claude Desktop ; http/sse exposent un écouteur réseau (hôte/port de liaison ci-dessous)
• CLICKHOUSE_MCP_BIND_HOST : Hôte auquel lier le serveur MCP lors de l'utilisation du transport HTTP ou SSE
  • Par défaut : "127.0.0.1"
  • Mettez à "0.0.0.0" pour lier à toutes les interfaces réseau (utile pour Docker ou l'accès à distance)
  • Utilisé uniquement lorsque le transport est "http" ou "sse" — sans rapport avec CLICKHOUSE_HOST
• CLICKHOUSE_MCP_BIND_PORT : Port auquel lier le serveur MCP lors de l'utilisation du transport HTTP ou SSE
  • Par défaut : "8000"
  • Utilisé uniquement lorsque le transport est "http" ou "sse" — sans rapport avec CLICKHOUSE_PORT
• CLICKHOUSE_MCP_QUERY_TIMEOUT : Délai d'attente en secondes pour les outils de requête
  • Par défaut : "30"
  • Augmentez cette valeur si vous voyez des erreurs Query timed out after ... pour les requêtes lourdes
• CLICKHOUSE_MCP_AUTH_TOKEN : Jeton porteur statique pour les transports HTTP/SSE
  • Par défaut : Aucun
  • L'un de CLICKHOUSE_MCP_AUTH_TOKEN, FASTMCP_SERVER_AUTH ou CLICKHOUSE_MCP_AUTH_DISABLED=true est requis pour les transports HTTP/SSE
  • Générez en utilisant uuidgen ou openssl rand -hex 32
  • Les clients doivent envoyer ce jeton dans l'en-tête Authorization: Bearer <token>
• FASTMCP_SERVER_AUTH : Déléguer l'authentification à un fournisseur d'authentification FastMCP
  • Par défaut : Aucun
  • La valeur est le chemin de classe complet d'une sous-classe AuthProvider, par exemple fastmcp.server.auth.providers.azure.AzureProvider ou fastmcp.server.auth.providers.google.GoogleProvider
  • Lorsqu'il est défini, FastMCP charge automatiquement le fournisseur à partir de ses propres variables d'environnement FASTMCP_SERVER_AUTH_* ; laissez CLICKHOUSE_MCP_AUTH_TOKEN non défini dans ce mode
• CLICKHOUSE_MCP_AUTH_DISABLED : Désactiver l'authentification pour les transports HTTP/SSE
  • Par défaut : "false" (l'authentification est activée)
  • Mettez à "true" pour désactiver l'authentification pour le développement/les tests locaux uniquement
  • AVERTISSEMENT : À utiliser uniquement pour le développement local. Ne pas désactiver en cas d'exposition aux réseaux

Variables de middleware

• MCP_MIDDLEWARE_MODULE : Nom du module Python contenant le middleware personnalisé à injecter dans le serveur MCP
  • Par défaut : Aucun (aucun middleware chargé)
  • Définissez le nom du module (sans l'extension .py) de votre module middleware
  • Le module doit fournir une fonction setup_middleware(mcp)
  • Voir Middleware personnalisé pour les détails et les exemples

Variables chDB

• CHDB_ENABLED : Activer/désactiver la fonctionnalité chDB
  • Par défaut : "false"
  • Mettez à "true" pour activer les outils chDB
  • Nécessite l'installation de l'extra optionnel : mcp-clickhouse[chdb]
• CHDB_DATA_PATH : Le chemin vers le répertoire de données chDB
  • Par défaut : ":memory:" (base de données en mémoire)
  • Utilisez :memory: pour une base de données en mémoire
  • Utilisez un chemin de fichier pour un stockage persistant (par exemple, /path/to/chdb/data)

Pièges de configuration courants

• CLICKHOUSE_SECURE vs MCP / TLS d'entrée — Désactiver CLICKHOUSE_SECURE parce que le serveur MCP se trouve derrière une entrée Kubernetes, un proxy inverse ou est atteint via HTTP simple ne désactive pas TLS pour la base de données ; cela change uniquement la façon dont ce processus se connecte à ClickHouse. Configurez le TLS d'entrée séparément des paramètres du client de base de données.
• Ports de protocole natif — CLICKHOUSE_PORT doit cibler l'interface HTTP de ClickHouse (8123/8443 par défaut). Les ports 9000/9440 sont destinés au protocole TCP natif (clickhouse-client) et ne fonctionneront pas avec ce serveur.
• Confusion d'hôte — CLICKHOUSE_HOST est le nom d'hôte de la base de données. CLICKHOUSE_MCP_BIND_HOST est uniquement l'adresse sur laquelle le serveur MCP HTTP/SSE écoute.

Exemples de configuration

Pour le développement local avec Docker :

# Required variables
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

# Optional: Override defaults for local development
CLICKHOUSE_SECURE=false  # Uses port 8123 automatically
CLICKHOUSE_VERIFY=false

Pour ClickHouse Cloud :

# Required variables
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password

# Optional: These use secure defaults
# CLICKHOUSE_SECURE=true  # Uses port 8443 automatically
# CLICKHOUSE_DATABASE=your_database

Pour ClickHouse SQL Playground :

CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
CLICKHOUSE_USER=demo
CLICKHOUSE_PASSWORD=
# Uses secure defaults (HTTPS on port 8443)

Pour chDB uniquement (en mémoire) :

# chDB configuration
CHDB_ENABLED=true
CLICKHOUSE_ENABLED=false
# CHDB_DATA_PATH defaults to :memory:

Pour chDB avec stockage persistant :

# chDB configuration
CHDB_ENABLED=true
CLICKHOUSE_ENABLED=false
CHDB_DATA_PATH=/path/to/chdb/data

Pour MCP Inspector ou l'accès à distance avec le transport HTTP :

CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_MCP_SERVER_TRANSPORT=http
CLICKHOUSE_MCP_BIND_HOST=0.0.0.0  # Bind to all interfaces
CLICKHOUSE_MCP_BIND_PORT=4200  # Custom port (default: 8000)
CLICKHOUSE_MCP_AUTH_TOKEN=your-generated-token  # One auth mode required for HTTP/SSE (or FASTMCP_SERVER_AUTH, or CLICKHOUSE_MCP_AUTH_DISABLED=true)

Pour le développement local avec le transport HTTP (authentification désactivée) :

CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_MCP_SERVER_TRANSPORT=http
CLICKHOUSE_MCP_AUTH_DISABLED=true  # Only for local development!

Lors de l'utilisation du transport HTTP, le serveur s'exécutera sur le port configuré (par défaut 8000). Par exemple, avec la configuration ci-dessus :

• Point de terminaison MCP : http://localhost:4200/mcp
• Vérification de l'état : http://localhost:4200/health

Vous pouvez définir ces variables dans votre environnement, dans un fichier .env ou dans la configuration de Claude Desktop :

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_DATABASE": "<optional-database>",
        "CLICKHOUSE_MCP_SERVER_TRANSPORT": "stdio",
        "CLICKHOUSE_MCP_BIND_HOST": "127.0.0.1",
        "CLICKHOUSE_MCP_BIND_PORT": "8000"
      }
    }
  }
}

Remarque : Les paramètres d'hôte et de port de liaison ne sont utilisés que lorsque le transport est défini sur « http » ou « sse ».

Exécution des tests

uv sync --all-extras --dev # install dev dependencies
uv run ruff check . # run linting

docker compose up -d test_services # start ClickHouse
uv run pytest -v tests
uv run pytest -v tests/test_tool.py # ClickHouse only
CHDB_ENABLED=true uv run --extra chdb pytest -v tests/test_chdb_tool.py # chDB only

Aperçu YouTube