Utiliser Spanner avec MCP Toolbox for Databases, la CLI Gemini et d'autres agents

Ce document explique comment connecter votre instance Spanner à différents outils de développement compatibles avec le protocole MCP (Model Context Protocol).

Nous vous recommandons d'utiliser l'extension Spanner dédiée pour Gemini CLI. L'extension regroupe les compétences sous-jacentes directement dans l'extension, ce qui simplifie la configuration. Vous pouvez configurer Gemini Code Assist pour qu'il utilise Gemini CLI, ce qui offre des avantages de configuration similaires dans votre IDE. Pour en savoir plus, consultez Extension Gemini CLI – Spanner.

Vous pouvez également connecter d'autres IDE et outils de développement compatibles avec le protocole MCP via MCP Toolbox for Databases. MCP Toolbox est un serveur MCP Open Source conçu pour connecter des agents d'IA à vos données. Il gère des tâches telles que l'authentification et le regroupement de connexions, ce qui vous permet d'interagir avec vos données en langage naturel directement depuis votre IDE.

Utiliser l'extension Gemini CLI dans Spanner

L'intégration de Spanner à Gemini CLI s'effectue via une extension Open Source qui offre des fonctionnalités supplémentaires par rapport à la connexion MCP Toolbox standard. L'extension propose un processus d'installation simplifié et un ensemble de compétences basées sur les outils MCP. Si vous utilisez l'extension Gemini CLI, vous n'avez pas besoin d'installer MCP Toolbox. Pour en savoir plus, consultez Extension Gemini CLI – Spanner.

L'extension spanner inclut des compétences permettant de lister les tables et d'exécuter des instructions SQL et SQL DQL.

Pour connaître toutes les compétences disponibles, consultez les compétences Spanner sur GitHub.

Avant de commencer

  1. Dans la Google Cloud console, sur la page de sélection du projet, sélectionnez ou créez un Google Cloud projet.

  2. Assurez-vous que la facturation est activée pour votre Google Cloud projet.

Configurer l'instance Spanner

  1. Activez l'API Spanner dans le Google Cloud projet.

  2. Créez ou sélectionnez une instance et une base de données Spanner.

  3. Configurez les rôles et autorisations requis pour effectuer cette tâche. L'utilisateur qui appelle les agents LLM a besoin des rôles suivants au niveau de la base de données :

    • Lecteur de bases de données Cloud Spanner (roles/spanner.databaseReader) pour exécuter des requêtes DQL et lister les tables.

    • Utilisateur de bases de données Cloud Spanner (roles/spanner.databaseUser) pour exécuter des requêtes LMD.

  4. Configurez les identifiants par défaut de l'application (ADC) pour votre environnement.

Installer MCP Toolbox

  1. Téléchargez la dernière version de MCP Toolbox en tant que fichier binaire. Sélectionnez le fichier binaire correspondant à votre système d'exploitation et à l'architecture de votre processeur. Vous devez utiliser la version 0.15.0 ou une version ultérieure de MCP Toolbox :

    linux/amd64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/version/linux/amd64/toolbox

    darwin/arm64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/version/darwin/arm64/toolbox

    darwin/amd64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/version/darwin/amd64/toolbox

    windows/amd64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/version/windows/amd64/toolbox

  2. Rendez le binaire exécutable :

    chmod +x toolbox

  3. Vérifiez l'installation :

    ./toolbox --version

Configurer les clients et les connexions

Cette section explique comment configurer différents outils de développement pour vous connecter à votre instance Spanner. Sélectionnez votre client parmi les options suivantes :

Gemini CLI

  1. Installez le Gemini CLI.
  2. Installez l'extension Spanner pour Gemini CLI à partir du dépôt GitHub à l'aide de la commande suivante : 
    gemini extensions install https://github.com/gemini-cli-extensions/spanner
  3. Définissez les variables d'environnement suivantes pour vous connecter à votre instance Spanner : 
    export SPANNER_PROJECT="PROJECT_ID"
export SPANNER_INSTANCE="INSTANCE_NAME"
export SPANNER_DATABASE="DATABASE_NAME"
export SPANNER_DIALECT="DIALECT_NAME"
     Remplacez les éléments suivants :
    • PROJECT_ID : ID du Google Cloud projet.
    • INSTANCE_NAME : nom de l'instance Spanner.
    • DATABASE_NAME : nom de la base de données Spanner.
    • DIALECT_NAME : dialecte SQL Spanner. Accepte googlesql ou postgresql. La valeur par défaut est googlesql si elle n'est pas définie.
  4. Démarrez Gemini CLI en mode interactif : 
    gemini

    La CLI charge automatiquement l'extension Spanner pour Gemini CLI et ses compétences, que vous pouvez utiliser pour interagir avec votre base de données.

    Dans Gemini CLI, utilisez la /extensions commande pour vérifier que l'extension est installée.

Gemini Code Assist

Nous vous recommandons vivement de configurer Gemini Code Assist pour qu'il utilise le Gemini CLI, car cette approche élimine la nécessité de configurer manuellement un serveur MCP. Toutefois, les instructions permettant de configurer manuellement un serveur MCP sont toujours disponibles dans la section suivante :


1. Installez l'extension Gemini Code Assist dans VS Code.
2. Activez le mode Agent et remplacez le modèle d'agent par Gemini.
3. Dans le répertoire racine de votre projet, créez un dossier nommé .gemini, puis un fichier settings.json dans ce dossier.
4. Ajoutez l'une des configurations suivantes en fonction de votre dialecte Spanner dans le fichier settings.json.
5. Remplacez les variables suivantes par vos valeurs :
  • PROJECT_ID: ID de votre Google Cloud projet.
  • INSTANCE_NAME : nom de votre instance Spanner.
  • DATABASE_NAME : nom de votre base de données Spanner.
6. Enregistrez le fichier.

Spanner avec le dialecte GoogleSQL : 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner avec le dialecte PostgreSQL : 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Claude Code

  1. Installez Claude Code.
  2. Définissez les variables d'environnement pour vous connecter à votre instance Spanner : 
    export SPANNER_PROJECT="PROJECT_ID"
export SPANNER_INSTANCE="INSTANCE_NAME"
export SPANNER_DATABASE="DATABASE_NAME"
export SPANNER_DIALECT="DIALECT_NAME"
     Remplacez les éléments suivants :
    • PROJECT_ID : ID du Google Cloud projet.
    • INSTANCE_NAME : nom de l'instance Spanner.
    • DATABASE_NAME : nom de la base de données Spanner.
    • DIALECT_NAME : dialecte SQL Spanner. Accepte googlesql ou postgresql. La valeur par défaut est googlesql si elle n'est pas définie.
  3. Démarrez l'agent : 
    claude
  4. Installez le plug-in : 
    /plugin install spanner@claude-plugins-official

Codex

  1. Installez la place de marché Data Agent Kit : 
    codex plugin marketplace add GoogleCloudPlatform/data-agent-kit
  2. Installez le plug-in Spanner : 
    codex plugin install spanner@data-agent-kit
  3. Configurez les variables d'environnement pour vous connecter à votre instance Spanner : 
    export SPANNER_PROJECT="PROJECT_ID"
export SPANNER_INSTANCE="INSTANCE_NAME"
export SPANNER_DATABASE="DATABASE_NAME"
export SPANNER_DIALECT="DIALECT_NAME"
     Remplacez les éléments suivants :
    • PROJECT_ID : ID du Google Cloud projet.
    • INSTANCE_NAME : nom de l'instance Spanner.
    • DATABASE_NAME : nom de la base de données Spanner.
    • DIALECT_NAME : dialecte SQL Spanner. Accepte googlesql ou postgresql. La valeur par défaut est googlesql si elle n'est pas définie.
  4. Facultatif. Mettez à jour la place de marché : 
    codex plugin marketplace upgrade data-agent-kit

Claude pour ordinateur


1. Ouvrez Claude pour ordinateur et accédez à Settings (Paramètres).
2. Dans l'onglet Developer (Développeur), cliquez sur Edit Config (Modifier la configuration) pour ouvrir le fichier de configuration.
3. Ajoutez l'une des configurations suivantes en fonction de votre dialecte Spanner, remplacez les variables d'environnement par vos valeurs, puis enregistrez le fichier :

Spanner avec le dialecte GoogleSQL : 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner avec le dialecte PostgreSQL : 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

4. Redémarrez Claude pour ordinateur.
5. Le nouvel écran de chat affiche une icône de marteau (MCP) avec le nouveau serveur MCP.

Cline


1. Ouvrez l'extension Cline dans VS Code et cliquez sur l'icône MCP Servers (Serveurs MCP).
2. Appuyez sur Configure MCP Servers (Configurer les serveurs MCP) pour ouvrir le fichier de configuration.
3. Ajoutez l'une des configurations suivantes en fonction de votre dialecte Spanner, remplacez les variables d'environnement par vos valeurs, puis enregistrez le fichier :

Spanner avec le dialecte GoogleSQL : 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner avec le dialecte PostgreSQL : 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Un état actif vert s'affiche une fois le serveur connecté.

Cursor


1. Créez le répertoire .cursor dans la racine de votre projet s'il n'existe pas.
2. Créez le fichier .cursor/mcp.json s'il n'existe pas et ouvrez-le.
3. Ajoutez l'une des configurations suivantes en fonction de votre dialecte Spanner, remplacez les variables d'environnement par vos valeurs, puis enregistrez le fichier :

Spanner avec le dialecte GoogleSQL : 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner avec le dialecte PostgreSQL : 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

4. Ouvrez Cursor et accédez à Settings > Cursor Settings > MCP (Paramètres > Paramètres du curseur > MCP). Un état actif vert s'affiche lorsque le serveur se connecte.

Visual Studio Code (Copilot)


1. Ouvrez VS Code et créez le répertoire .vscode dans la racine de votre projet s'il n'existe pas.
2. Créez le fichier .vscode/mcp.json s'il n'existe pas et ouvrez-le.
3. Ajoutez l'une des configurations suivantes en fonction de votre dialecte Spanner, remplacez les variables d'environnement par vos valeurs, puis enregistrez le fichier :

Spanner avec le dialecte GoogleSQL : 

{
  "servers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
        "SPANNER_PROJECT": "PROJECT_ID",
        "SPANNER_INSTANCE": "INSTANCE_NAME",
        "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner avec le dialecte PostgreSQL : 

{
  "servers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
        "SPANNER_PROJECT": "PROJECT_ID",
        "SPANNER_INSTANCE": "INSTANCE_NAME",
        "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Windsurf


1. Ouvrez Windsurf et accédez à l'assistant Cascade.
2. Cliquez sur l'icône MCP, puis sur Configure (Configurer) pour ouvrir le fichier de configuration.
3. Ajoutez l'une des configurations suivantes en fonction de votre dialecte Spanner, remplacez les variables d'environnement par vos valeurs, puis enregistrez le fichier :

Spanner avec le dialecte GoogleSQL : 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner avec le dialecte PostgreSQL : 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Se connecter avec Antigravity

Vous pouvez connecter Spanner à Antigravity de plusieurs façons :

  • À l'aide de MCP Store
  • À l'aide d'une configuration personnalisée

MCP Store

La méthode la plus recommandée pour se connecter à Antigravity consiste à utiliser MCP Store intégré.

  1. Ouvrez Antigravity et ouvrez le panneau de l'agent de l'éditeur.
  2. Cliquez sur l'icône Menu en haut du panneau, puis sélectionnez MCP Servers (Serveurs MCP).
  3. Recherchez Spanner dans la liste des serveurs disponibles, puis cliquez sur Install (Installer).
  4. Suivez les étapes à l'écran pour autoriser Antigravity à accéder à votre projet Google Cloud. Cela permet à Antigravity d'accéder à l'instance Spanner de votre projet.

Une fois le serveur Spanner installé dans MCP Store, les ressources et les compétences du serveur sont disponibles pour l'éditeur.

Configuration personnalisée

Pour vous connecter à un serveur MCP personnalisé, procédez comme suit :

  1. Ouvrez Antigravity et ouvrez le panneau de l'agent de l'éditeur.
  2. Cliquez sur l'icône Menu en haut du panneau, puis sélectionnez MCP Servers (Serveurs MCP).
  3. Cliquez sur Manage MCP Servers > View raw config (Gérer les serveurs MCP > Afficher la configuration brute) pour ouvrir le fichier mcp_config.json.
  4. Ajoutez la configuration suivante, remplacez les variables d'environnement par vos valeurs, puis enregistrez.
{
  "mcpServers": {
    "spanner": {
      "command": "npx",
      "args": ["-y","@toolbox-sdk/server","--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME",
          "SPANNER_DIALECT": "DIALECT_NAME"
      }
    }
  }
}

Une fois le serveur MCP personnalisé configuré, les ressources et les compétences du serveur Spanner sont disponibles pour l'éditeur.

Remplacez les éléments suivants :

  • PROJECT_ID: ID de votre Google Cloud projet.
  • INSTANCE_NAME : nom de votre instance Spanner.
  • DATABASE_NAME : nom de votre base de données Spanner.
  • DIALECT_NAME : dialecte SQL Spanner. Accepte googlesql ou postgresql. Si vous ne spécifiez pas de dialecte, la valeur par défaut est googlesql.

Se connecter à Spanner dans VS Code à l'aide de l'extension Data Agent Kit

L'extension Google Cloud Data Agent Kit vous permet de gérer votre base de données Spanner et d'exécuter des requêtes sur vos données Spanner dans l'IDE de votre choix. Visual Studio Code et tous les IDE basés sur VS Code sont compatibles.

Cette extension fournit des fonctionnalités de découverte et d'exploration des données, ce qui vous permet de poser des questions sur vos données Spanner en langage naturel. Elle permet d'éviter de passer d'un contexte à l'autre entre les outils de ligne de commande Spanner et votre environnement de développement. Data Agent Kit fournit également des plug-ins CLI à utiliser avec vos Google Cloud ressources.

Pour en savoir plus, consultez la présentation de l'extension Data Agent Kit pour VS Code.