Adrienne Vermorel

Serveur MCP BigQuery : guide complet d'installation

3 février 2026

Je voulais que mon assistant IA puisse interroger BigQuery directement. Sans copier-coller de résultats SQL, sans basculer constamment entre la console GCP et Claude. Google propose désormais deux méthodes officielles pour cela, toutes deux basées sur le Model Context Protocol (MCP).

Ce guide couvre les deux options : le Remote MCP Server managé et le MCP Toolbox for Databases auto-hébergé. J’ai testé les deux avec Claude Desktop et Claude Code, et j’ai constaté des différences importantes en termes de complexité d’installation et de gestion de l’authentification.

Pour les utilisateurs de Claude Code : le CLI bq fonctionne souvent mieux que MCP pour un usage interactif. Claude peut exécuter directement des commandes bq query sans aucune configuration. MCP apporte de la valeur pour les requêtes paramétrées personnalisées, les workflows multi-bases, ou quand vous avez besoin de traces d’audit structurées. Ce guide vous aide à déterminer quelle option correspond à votre cas d’usage.

Deux options officielles

Le Remote MCP Server s’exécute entièrement sur l’infrastructure de Google. Vous l’activez via gcloud, configurez votre client, et commencez à interroger vos données. Pas de serveur à gérer. Cependant, il nécessite une gestion manuelle des tokens avec Claude Code (les tokens expirent toutes les heures), ce qui le rend peu pratique pour une utilisation régulière en dehors de Claude Desktop.

Le MCP Toolbox est un binaire open source que vous exécutez localement ou déployez vous-même. Il offre plus d’outils, supporte plusieurs bases de données au-delà de BigQuery, et vous permet de définir des requêtes paramétrées personnalisées. L’authentification utilise Application Default Credentials (ADC), ce qui fonctionne plus naturellement mais nécessite de comprendre la différence entre ADC et l’authentification gcloud classique.

Pour Claude Desktop, le Remote Server convient bien pour l’exploration de base. Pour Claude Code, le Toolbox est le choix pragmatique.

Option 1 : Remote MCP Server

Le Remote Server expose BigQuery via un endpoint unique : https://bigquery.googleapis.com/mcp. Aucune installation locale requise.

Il fournit cinq outils : list_dataset_ids, get_dataset_info, list_table_ids, get_table_info et execute_sql. Cela couvre l’essentiel : l’assistant IA peut découvrir vos datasets, examiner les schémas de tables et exécuter des requêtes SQL.

Installation

Activez le service MCP pour votre projet Google Cloud :

gcloud beta services mcp enable bigquery.googleapis.com \
  --project=PROJECT_ID

Remplacez PROJECT_ID par l’identifiant réel de votre projet.

Rôles IAM requis

L’utilisateur ou le compte de service a besoin de roles/bigquery.user (pour exécuter des requêtes et lister les datasets) et roles/bigquery.dataViewer (pour lire les données des tables).

Pour un usage en production avec un compte de service :

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:SA_EMAIL" \
  --role="roles/bigquery.user"

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:SA_EMAIL" \
  --role="roles/bigquery.dataViewer"

Configuration Claude Desktop

Pour Claude Desktop, ajoutez le Remote Server à votre fichier de configuration situé à ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows) :

{
  "mcpServers": {
    "bigquery-remote": {
      "url": "https://bigquery.googleapis.com/mcp",
      "env": {
        "GOOGLE_CLOUD_PROJECT": "your-project-id"
      }
    }
  }
}

Claude Desktop gère automatiquement OAuth avec cette configuration.

Configuration Claude Code

Claude Code nécessite une gestion manuelle des tokens pour le Remote MCP Server. La syntaxe de configuration diffère de Claude Desktop. Ajoutez ceci à votre .mcp.json :

{
  "mcpServers": {
    "bigquery": {
      "type": "http",
      "url": "https://bigquery.googleapis.com/mcp",
      "headers": {
        "Authorization": "Bearer <ACCESS_TOKEN>",
        "x-goog-user-project": "your-project-id"
      }
    }
  }
}

Obtenez votre token d’accès avec :

gcloud auth print-access-token

Le token expire au bout d’une heure environ. Vous devez le rafraîchir manuellement et redémarrer Claude Code quand il expire. Cela rend le Remote MCP Server peu pratique pour une utilisation régulière avec Claude Code. Pour Claude Code, passez directement à l’Option 2 (le Toolbox), qui gère l’authentification de manière plus élégante.

Option 2 : MCP Toolbox

Le MCP Toolbox est open source (https://github.com/googleapis/genai-toolbox, Apache 2.0) et s’exécute comme un binaire local. À la version 0.22.0, il est encore en bêta.

Au-delà des outils de base du Remote Server, le Toolbox ajoute bigquery-forecast (prévisions de séries temporelles via BigQuery ML), bigquery-conversational-analytics, bigquery-search-catalog (intégration Data Catalog), et surtout bigquery-sql pour exécuter des requêtes paramétrées prédéfinies. Ce dernier est utile quand vous voulez donner à l’assistant IA un accès structuré à vos données sans autoriser du SQL arbitraire.

Installation du Toolbox

Téléchargez le binaire, configurez l’authentification et définissez les variables d’environnement.

macOS (Apple Silicon) :

export VERSION=0.22.0
curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/arm64/toolbox
chmod +x toolbox

macOS (Intel) :

export VERSION=0.22.0
curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/amd64/toolbox
chmod +x toolbox

Linux (AMD64) :

export VERSION=0.22.0
curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

Via Homebrew :

brew install mcp-toolbox

Via NPX (sans installation locale) :

npx -y @toolbox-sdk/server --prebuilt bigquery --stdio

NPX est pratique pour tester mais ajoute de la latence au démarrage. Pour la production, téléchargez le binaire.

Authentification

Le Toolbox utilise Application Default Credentials (ADC), pas vos credentials gcloud auth login habituels. C’est une source de confusion fréquente.

La commande gcloud auth login authentifie les commandes du CLI gcloud. ADC est un credential séparé utilisé par les applications et les SDK. Vous avez besoin des deux :

# Ceci authentifie les commandes du CLI gcloud (vous l'avez probablement déjà fait)
gcloud auth login

# Ceci configure ADC, que le serveur MCP utilise
gcloud auth application-default login

La seconde commande ouvre un navigateur pour le consentement OAuth. Une fois terminé, les credentials sont stockés dans ~/.config/gcloud/application_default_credentials.json.

Pour la production, utilisez un fichier de clé de compte de service et définissez GOOGLE_APPLICATION_CREDENTIALS :

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"

Vous devez aussi définir le projet :

export BIGQUERY_PROJECT="your-project-id"

Puis lancez le serveur :

./toolbox --prebuilt bigquery --stdio

Le flag --stdio lance en mode stdio, ce qu’attendent les clients MCP comme Claude Desktop.

Important : après avoir mis à jour les credentials, vous devez redémarrer Claude Code ou Claude Desktop. Le serveur MCP lit les credentials au démarrage et ne détecte pas les changements en cours d’exécution.

Exemples de configuration

Claude Desktop avec binaire local

{
  "mcpServers": {
    "bigquery": {
      "command": "/Users/yourname/tools/toolbox",
      "args": ["--prebuilt", "bigquery", "--stdio"],
      "env": {
        "BIGQUERY_PROJECT": "your-project-id"
      }
    }
  }
}

Remplacez le chemin par l’emplacement où vous avez placé le binaire.

Configuration basée sur NPX

{
  "mcpServers": {
    "bigquery": {
      "command": "npx",
      "args": ["-y", "@toolbox-sdk/server", "--prebuilt", "bigquery", "--stdio"],
      "env": {
        "BIGQUERY_PROJECT": "your-project-id"
      }
    }
  }
}

Le flag -y accepte automatiquement le téléchargement NPX.

Configuration Claude Code

claude mcp add bigquery -- npx -y @toolbox-sdk/server --prebuilt bigquery --stdio

Puis éditez pour ajouter la variable d’environnement :

claude mcp edit bigquery

Ajoutez la variable BIGQUERY_PROJECT dans l’éditeur qui s’ouvre.

Pour les projets d’équipe, vous pouvez créer une configuration scopée au projet :

claude mcp add bigquery -s project -- npx -y @toolbox-sdk/server --prebuilt bigquery --stdio

Cela crée un fichier .mcp.json à la racine de votre projet que vous pouvez commiter.

Outils personnalisés

Le Toolbox supporte les définitions d’outils personnalisés via un fichier tools.yaml. Pour les équipes data, c’est la fonctionnalité la plus utile : vous pouvez définir des requêtes paramétrées qui contraignent ce que l’IA peut exécuter tout en permettant de la flexibilité sur les paramètres.

sources:
  my-bigquery-source:
    kind: bigquery
    project: your-project-id

tools:
  search_orders_by_date:
    kind: bigquery-sql
    source: my-bigquery-source
    description: Search orders within a date range
    statement: |
      SELECT
        order__id,
        order__customer_id,
        order__total_amount_usd,
        order__created_at
      FROM `your-project.ecommerce.mrt__sales__orders`
      WHERE order__created_at BETWEEN @start_date AND @end_date
      ORDER BY order__created_at DESC
      LIMIT 100
    parameters:
      - name: start_date
        type: string
        description: Start date (YYYY-MM-DD)
      - name: end_date
        type: string
        description: End date (YYYY-MM-DD)

  get_customer_metrics:
    kind: bigquery-sql
    source: my-bigquery-source
    description: Get aggregated metrics for a customer
    statement: |
      SELECT
        customer__id,
        customer__orders,
        customer__lifetime_value_usd,
        customer__last_ordered_at
      FROM `your-project.ecommerce.mrt__sales__customers`
      WHERE customer__id = @customer_id
    parameters:
      - name: customer_id
        type: string
        description: The customer ID to look up

Lancez avec votre configuration personnalisée :

./toolbox --tools tools.yaml --stdio

Cette approche contrôle exactement quelles requêtes l’IA peut exécuter et quels paramètres elle peut faire varier. Bien plus sûr que l’exécution de SQL arbitraire.

Configuration du compte de service

Pour la production, créez un compte de service dédié avec des permissions minimales :

# Créer le compte de service
gcloud iam service-accounts create bigquery-mcp \
  --display-name="BigQuery MCP Service Account"

# Attribuer les rôles
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:bigquery-mcp@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/bigquery.user"

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:bigquery-mcp@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/bigquery.dataViewer"

# Créer le fichier de clé
gcloud iam service-accounts keys create bigquery-mcp-key.json \
  --iam-account=bigquery-mcp@PROJECT_ID.iam.gserviceaccount.com

Puis définissez GOOGLE_APPLICATION_CREDENTIALS pour pointer vers le fichier de clé. La clé doit être renouvelée périodiquement.

Pour les applications destinées aux utilisateurs finaux où les requêtes doivent s’exécuter avec les permissions de chaque utilisateur, vous pouvez configurer OAuth 2.0 via l’Agent Development Kit de Google. La mise en place est plus complexe mais vous donne des traces d’audit par utilisateur.

Ce que vous pouvez faire avec

Une fois configuré, l’interaction avec BigQuery se fait en langage naturel.

Demander “liste tous les datasets de mon projet” déclenche list_dataset_ids. “Montre-moi le schéma de la table customers dans le dataset sales” appelle get_table_info. “Quelles sont les 10 commandes avec le plus gros revenu ce mois-ci ?” pousse l’assistant à écrire et exécuter du SQL.

Je trouve cela particulièrement utile pour les vérifications rapides de qualité des données. “Compte les valeurs nulles dans la colonne email”, “trouve les doublons de customer_id” ou “y a-t-il des commandes avec des montants négatifs ?” sont le genre de questions où écrire le SQL n’est pas difficile, mais le changement de contexte finit par peser. Laisser l’assistant s’en charger pendant que je reste dans mon éditeur est sensiblement plus rapide.

Le reporting ad hoc fonctionne aussi : “résumé des ventes mensuelles pour 2025 par catégorie de produit” ou “compare le revenu du Q4 2025 avec le Q4 2024 par région”. L’assistant écrit le SQL, l’exécute et formate les résultats.

Dépannage

Échecs silencieux sur list tools

Quand les permissions manquent, list_dataset_ids et les outils similaires peuvent retourner des résultats vides sans message d’erreur. L’outil execute_sql retourne une erreur 403 claire, mais les opérations list échouent silencieusement.

Si vous obtenez des résultats vides alors que vous attendez des données :

Vérifiez que ADC est configuré : gcloud auth application-default print-access-token doit retourner un token
Vérifiez le projet : echo $BIGQUERY_PROJECT doit afficher votre ID de projet
Testez avec execute_sql à la place, qui donne des erreurs plus claires

Si vous avez exécuté gcloud auth login mais obtenez toujours des erreurs de permission, vous avez probablement besoin d’ADC :

gcloud auth application-default login

Puis redémarrez Claude Code ou Claude Desktop.

Credentials non pris en compte après modification

Le serveur MCP lit les credentials au démarrage. Si vous mettez à jour les credentials pendant que Claude tourne, redémarrez l’application. Avec Claude Code, vous devrez peut-être redémarrer deux fois (une fois pour charger la nouvelle config, une fois pour les nouveaux credentials).

Coûts et pièges

Les deux options sont encore en preview/bêta, attendez-vous à des breaking changes. Fixez une version spécifique en production.

Le plus gros souci concerne les coûts de requêtes. Chaque appel execute_sql exécute une requête BigQuery, et les coûts dépendent du volume de données scannées. Une IA curieuse qui pose des questions larges sur de grosses tables peut accumuler des frais. Pour limiter les risques : utilisez des requêtes paramétrées personnalisées avec des clauses LIMIT, restreignez l’accès à des datasets spécifiques, et mettez en place des contrôles de coûts BigQuery.

Côté permissions : execute_sql peut techniquement exécuter des statements INSERT, UPDATE, DELETE et DDL. Pour un accès en lecture seule, n’accordez que roles/bigquery.dataViewer ou utilisez des outils bigquery-sql personnalisés avec des requêtes read-only. Évitez roles/bigquery.dataEditor.

Autres points à surveiller : les requêtes longues peuvent timeout, les gros result sets sont tronqués, et vous pouvez atteindre les limites de requêtes concurrentes de BigQuery.

Quand utiliser MCP vs CLI

Avant de vous engager dans la configuration MCP, demandez-vous si le CLI bq ne serait pas plus simple. Claude Code peut exécuter directement bq query, bq ls et bq show sans aucune configuration. Le CLI utilise vos credentials gcloud habituels, ne nécessite pas de redémarrage de serveur après changement d’auth, et donne des messages d’erreur plus clairs.

MCP apporte de la valeur dans des scénarios spécifiques :

Requêtes paramétrées personnalisées : le fichier tools.yaml du Toolbox vous permet de définir exactement quelles requêtes l’IA peut exécuter avec quels paramètres. C’est plus sûr que du SQL arbitraire et utile quand vous construisez des workflows IA qui ne doivent accéder qu’à des patterns de données spécifiques.

Workflows multi-bases : si vous travaillez sur BigQuery, Cloud SQL, Spanner ou d’autres bases, le Toolbox fournit une interface unifiée plutôt que de basculer entre les CLI.

Output d’outils structurés : MCP retourne des données structurées que Claude peut parser plus fiablement que l’output CLI. Pour les pipelines automatisés où vous avez besoin de formats de réponse prévisibles, MCP réduit les erreurs de parsing.

Exigences d’audit : chaque appel d’outil MCP crée une entrée de log structurée. Si la conformité exige des traces d’audit des accès données par l’IA, MCP le fournit par défaut.

Pour l’exploration interactive, le CLI est souvent plus rapide à configurer et utiliser. Pour les workflows automatisés ou les patterns d’accès contraints, MCP vaut la surcharge de configuration.

Quelle option MCP choisir

Si vous décidez que MCP correspond à votre cas d’usage :

Pour Claude Desktop : commencez avec le Remote Server. Il fonctionne avec une configuration minimale et couvre la plupart des besoins d’exploration.

Pour Claude Code : utilisez le Toolbox. L’expiration des tokens du Remote Server le rend peu pratique pour une utilisation régulière.

Pour les équipes : le Toolbox avec un tools.yaml partagé vous permet d’encoder les requêtes courantes et la logique métier. Cela donne aux assistants IA un accès structuré à vos données sans les risques du SQL arbitraire.

Serveur MCP BigQuery : guide complet d'installation

Deux options officielles

Option 1 : Remote MCP Server

Installation

Rôles IAM requis

Configuration Claude Desktop

Configuration Claude Code

Option 2 : MCP Toolbox

Installation du Toolbox

Authentification

Exemples de configuration

Claude Desktop avec binaire local

Configuration basée sur NPX

Configuration Claude Code

Outils personnalisés

Configuration du compte de service

Ce que vous pouvez faire avec

Dépannage

Échecs silencieux sur list tools

Erreurs d’authentification après gcloud auth login

Credentials non pris en compte après modification

Coûts et pièges

Quand utiliser MCP vs CLI

Quelle option MCP choisir