Configuration de la MCP Toolbox BigQuery

La MCP Toolbox for Databases est l’option open source (Apache 2.0) de Google pour connecter les assistants IA à BigQuery. Contrairement au Remote MCP Server, vous l’exécutez vous-même — en tant que binaire local, via NPX, ou déployé sur votre propre infrastructure. La contrepartie : une installation plus complexe en échange de plus d’outils, d’une meilleure authentification, d’un support multi-bases de données, et du support des requêtes paramétrées personnalisées.

Pour les utilisateurs de Claude Code, la Toolbox est le choix pratique : elle utilise les Application Default Credentials (ADC) plutôt que des tokens renouvelés manuellement. Depuis la v0.22.0, la Toolbox est encore en bêta.

Ce qu’elle apporte au-delà du Remote Server

Le Remote Server vous donne cinq outils de base. La Toolbox ajoute :

bigquery-forecast — prévisions de séries temporelles via BigQuery ML
bigquery-conversational-analytics — analytics en langage naturel
bigquery-search-catalog — intégration Data Catalog pour la découverte de datasets
bigquery-sql — exécuter des requêtes paramétrées prédéfinies

L’outil bigquery-sql est le plus pertinent pour les équipes data : il offre un accès structuré aux données sans permettre de SQL arbitraire, ce qui est plus sûr pour un usage en production.

Installation

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 ajoute une latence au démarrage. Pour une utilisation régulière, téléchargez le binaire.

Authentification

La Toolbox utilise les Application Default Credentials (ADC). C’est l’obstacle le plus fréquent dans l’installation — l’ADC est une credential distincte de votre authentification gcloud auth login habituelle. Consultez la note dédiée sur les GCP Application Default Credentials pour l’explication complète.

En résumé : exécutez les deux commandes :

# Your regular gcloud CLI auth (you probably already have this)
gcloud auth login

# ADC -- what the Toolbox actually uses
gcloud auth application-default login

La deuxième commande ouvre un navigateur pour le consentement OAuth. Les credentials se trouvent dans ~/.config/gcloud/application_default_credentials.json.

Pour la production, utilisez une clé de compte de service :

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

Définissez votre projet :

export BIGQUERY_PROJECT="your-project-id"

Puis démarrez le serveur :

./toolbox --prebuilt bigquery --stdio

Le flag --stdio exécute en mode stdio, ce qui est ce qu’attendent les clients MCP comme Claude Desktop. Cela correspond au transport stdio décrit dans Architecture du protocole MCP.

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 pendant son exécution. Avec Claude Code, vous devrez peut-être redémarrer deux fois — une fois pour la nouvelle configuration, une fois pour les credentials.

Configuration Claude Desktop

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

Remplacez le chemin de la commande par l’emplacement où vous avez installé le binaire.

Pour la variante NPX :

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

Configuration Claude Code

Le chemin le plus rapide :

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

Puis ajoutez la variable d’environnement :

claude mcp edit bigquery

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

Pour les projets d’équipe, utilisez une configuration à portée de projet que vous pouvez committer :

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. Les membres de l’équipe clonent le dépôt et obtiennent automatiquement la même configuration MCP — aucune installation manuelle par développeur.

Résolution des problèmes

Échecs silencieux sur les opérations de liste

Quand les permissions sont manquantes, list_dataset_ids et les outils similaires peuvent retourner des résultats vides sans aucune erreur. L’outil execute_sql donne des erreurs 403 claires, mais les opérations de liste échouent silencieusement.

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

Vérifiez que l’ADC est configuré : gcloud auth application-default print-access-token doit retourner un token
Vérifiez le projet : echo $BIGQUERY_PROJECT doit afficher l’ID de votre projet
Testez avec execute_sql à la place — cela donne des messages d’erreur plus clairs

Si gcloud auth login fonctionne mais que la Toolbox donne des erreurs de permission, vous avez besoin de l’ADC :

gcloud auth application-default login

Puis redémarrez votre client MCP.

Credentials non pris en compte après les modifications

Le serveur MCP lit les credentials une seule fois au démarrage. Mettez à jour les credentials, puis redémarrez l’application. C’est la question la plus fréquente de type “pourquoi ça ne fonctionne pas”, et la réponse est toujours “avez-vous redémarré ?”