Este documento descreve como conectar sua instância do Spanner a várias ferramentas de desenvolvedor que oferecem suporte ao Protocolo de Contexto de Modelo (MCP).
Recomendamos usar a extensão dedicada do Spanner para a CLI do Gemini. A extensão agrupa as habilidades subjacentes diretamente nela, o que simplifica a configuração. Você pode configurar o Gemini Code Assist para usar a CLI do Gemini, oferecendo benefícios de configuração semelhantes no seu ambiente de desenvolvimento integrado. Para mais informações, consulte Extensão da CLI do Gemini: Spanner.
Como alternativa, outros ambientes de desenvolvimento integrado (IDEs) e ferramentas para desenvolvedores que oferecem suporte ao MCP podem se conectar usando a MCP Toolbox for Databases. A MCP Toolbox é um servidor MCP de código aberto projetado para conectar agentes de IA aos seus dados. Ele processa tarefas como autenticação e agrupamento de conexões, permitindo que você interaja com seus dados em linguagem natural diretamente do seu ambiente de desenvolvimento integrado.
Usar a extensão da CLI do Gemini no Spanner
A integração do Spanner com a CLI do Gemini é feita por uma extensão de código aberto que oferece mais recursos em comparação com a conexão padrão do MCP Toolbox. A extensão oferece um processo de instalação simplificado e um conjunto de habilidades com base nas ferramentas do MCP. Se você usa a extensão da CLI do Gemini, não precisa instalar a caixa de ferramentas do MCP. Para mais informações, consulte Extensão da CLI do Gemini - Spanner.
A extensão spanner inclui habilidades para listar tabelas e executar instruções SQL e SQL DQL.
Para conferir todas as habilidades disponíveis, consulte as habilidades do Spanner no GitHub.
Antes de começar
No console do Google Cloud , na página do seletor de projetos, selecione ou crie um projeto do Google Cloud .
Verifique se o faturamento está ativado para o projeto do Google Cloud .
Configurar a instância do Spanner
Crie ou selecione uma instância e um banco de dados do Spanner.
Configure os papéis e as permissões necessárias para concluir essa tarefa. O usuário que invoca os agentes de LLM precisa das seguintes funções no nível do banco de dados:
Leitor do banco de dados do Cloud Spanner (
roles/spanner.databaseReader) para executar consultas DQL e listar tabelas.Usuário do banco de dados do Cloud Spanner (
roles/spanner.databaseUser) para executar consultas DML.
Configure as Credenciais padrão do aplicativo (ADC) para seu ambiente.
Instalar o MCP Toolbox
Faça o download da versão mais recente da MCP Toolbox como um binário. Selecione o binário correspondente ao seu sistema operacional e à arquitetura de CPU. Use a versão 0.15.0 ou mais recente da 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
Torne o binário executável:
chmod +x toolboxVerifique a instalação:
./toolbox --version
Configurar clientes e conexões
Nesta seção, descrevemos como configurar várias ferramentas de desenvolvedor para se conectar à sua instância do Spanner. Selecione seu cliente entre as seguintes opções:
CLI do Gemini
- Instale a CLI do Gemini.
- Instale a extensão do Spanner para a CLI do Gemini no repositório do GitHub usando o seguinte comando:
gemini extensions install https://github.com/gemini-cli-extensions/spanner
- Defina as variáveis de ambiente a seguir para se conectar à sua
instância do Spanner:
export SPANNER_PROJECT="PROJECT_ID" export SPANNER_INSTANCE="INSTANCE_NAME" export SPANNER_DATABASE="DATABASE_NAME" export SPANNER_DIALECT="DIALECT_NAME"
- PROJECT_ID: o ID do projeto do Google Cloud .
- INSTANCE_NAME: o nome da instância do Spanner.
- DATABASE_NAME: o nome do banco de dados do Spanner.
- DIALECT_NAME: o dialeto SQL do Spanner. Aceita
googlesqloupostgresql. O padrão égooglesqlse não estiver definido.
- Inicie a CLI do Gemini no modo interativo:
gemini
A CLI carrega automaticamente a extensão do Spanner para a CLI do Gemini e as habilidades dela, que você pode usar para interagir com seu banco de dados.
Na CLI do Gemini, use o comando
/extensionspara verificar se a extensão está instalada.
Gemini Code Assist
Recomendamos configurar o Gemini Code Assist para usar a CLI do Gemini, já que essa abordagem elimina a necessidade de configurar manualmente um servidor MCP. No entanto, as instruções para configurar manualmente um servidor MCP ainda estão disponíveis na seção a seguir:
1. Instale a extensão Gemini Code Assist no VS Code.
2. Ative o modo agente e mude o modelo para o Gemini.
3. No diretório raiz do projeto, crie uma pasta chamada
.gemini e, dentro dela, um arquivo settings.json.4. Adicione uma das seguintes configurações com base no seu dialeto do Spanner no arquivo
settings.json.5. Substitua as seguintes variáveis pelos seus valores:
PROJECT_ID: o ID do projeto Google Cloud .INSTANCE_NAME: o nome da instância do Spanner.DATABASE_NAME: o nome do banco de dados do Spanner.
Spanner com dialeto 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 com dialeto 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
- Instale o Claude Code.
- Defina as variáveis de ambiente para se conectar à instância do Spanner:
export SPANNER_PROJECT="PROJECT_ID" export SPANNER_INSTANCE="INSTANCE_NAME" export SPANNER_DATABASE="DATABASE_NAME" export SPANNER_DIALECT="DIALECT_NAME"
- PROJECT_ID: o ID do projeto do Google Cloud .
- INSTANCE_NAME: o nome da instância do Spanner.
- DATABASE_NAME: o nome do banco de dados do Spanner.
- DIALECT_NAME: o dialeto SQL do Spanner. Aceita
googlesqloupostgresql. O padrão égooglesqlse não estiver definido.
- Inicie o agente:
claude
- Instalar o plug-in:
/plugin install spanner@claude-plugins-official
Codex
- Instale o Data Agent Kit no Marketplace:
codex plugin marketplace add GoogleCloudPlatform/data-agent-kit
- Instale o plug-in do Spanner:
codex plugin install spanner@data-agent-kit
- Configure as variáveis de ambiente para se conectar à sua instância do Spanner:
export SPANNER_PROJECT="PROJECT_ID" export SPANNER_INSTANCE="INSTANCE_NAME" export SPANNER_DATABASE="DATABASE_NAME" export SPANNER_DIALECT="DIALECT_NAME"
- PROJECT_ID: o ID do projeto do Google Cloud .
- INSTANCE_NAME: o nome da instância do Spanner.
- DATABASE_NAME: o nome do banco de dados do Spanner.
- DIALECT_NAME: o dialeto SQL do Spanner. Aceita
googlesqloupostgresql. O padrão égooglesqlse não estiver definido.
- Opcional. Atualize o marketplace:
codex plugin marketplace upgrade data-agent-kit
Claude para computador
1. Abra o Claude para computador e acesse Configurações.
2. Na guia Desenvolvedor, clique em Editar configuração para abrir o arquivo de configuração.
3. Adicione uma das seguintes configurações com base no dialeto do Spanner, substitua as variáveis de ambiente pelos seus valores e salve o arquivo:
Spanner com dialeto 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 com dialeto 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. Reinicie o Claude para computador.
5. A nova tela de chat mostra um ícone de martelo (MCP) com o novo servidor MCP.
Cline
1. Abra a extensão Cline no VS Code e clique no ícone Servidores MCP.
2. Toque em "Configurar servidores MCP" para abrir o arquivo de configuração.
3. Adicione uma das seguintes configurações com base no dialeto do Spanner, substitua as variáveis de ambiente pelos seus valores e salve o arquivo:
Spanner com dialeto 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 com dialeto 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"
}
}
}
}
Um status ativo verde aparece depois que o servidor se conecta.
Cursor
1. Crie o diretório
.cursor na raiz do projeto, se ele não existir. 2. Crie o arquivo
.cursor/mcp.json, se ele não existir, e abra-o.3. Adicione uma das seguintes configurações com base no dialeto do Spanner, substitua as variáveis de ambiente pelos seus valores e salve o arquivo:
Spanner com dialeto 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 com dialeto 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. Abra Cursor e navegue até Configurações > Configurações do cursor > MCP. Um status ativo verde aparece quando o servidor se conecta.
Visual Studio Code (Copilot)
1. Abra o VS Code e crie o diretório
.vscode na raiz do projeto, se ele não existir. 2. Crie o arquivo
.vscode/mcp.json, se ele não existir, e abra-o. 3. Adicione uma das seguintes configurações com base no dialeto do Spanner, substitua as variáveis de ambiente pelos seus valores e salve o arquivo:
Spanner com dialeto 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 com dialeto 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. Abra o Windsurf e navegue até o assistente do Cascade.
2. Clique no ícone do MCP e em Configurar para abrir o arquivo de configuração.
3. Adicione uma das seguintes configurações com base no dialeto do Spanner, substitua as variáveis de ambiente pelos seus valores e salve o arquivo:
Spanner com dialeto 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 com dialeto 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"
}
}
}
}
Conecte-se com o Antigravity
É possível conectar o Spanner ao Antigravity das seguintes maneiras:
- Como usar a loja do MCP
- Usar uma configuração personalizada
Loja MCP
A maneira mais recomendada de se conectar ao Antigravity é usando a loja MCP integrada.
- Abra o Antigravity e o painel do agente do editor.
- Clique no ícone Menu na parte de cima do painel e selecione Servidores MCP.
- Localize Spanner na lista de servidores disponíveis e clique em Instalar.
- Siga as etapas na tela para autorizar o Antigravity a acessar seu projeto do Google Cloud. Isso permite que o Antigravity acesse a instância do Spanner no seu projeto.
Depois de instalar o servidor do Spanner na loja do MCP, os recursos e as habilidades do servidor ficam disponíveis para o editor.
Configuração personalizada
Para se conectar a um servidor MCP personalizado, siga estas etapas:
- Abra o Antigravity e o painel do agente do editor.
- Clique no ícone Menu na parte de cima do painel e selecione Servidores MCP.
- Clique em Gerenciar servidores MCP > Ver configuração bruta para abrir o arquivo
mcp_config.json. - Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e salve.
{
"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"
}
}
}
}
Depois de configurar o servidor MCP personalizado, os recursos e as habilidades do servidor do Spanner ficam disponíveis para o editor.
Substitua:
PROJECT_ID: o ID do projeto Google Cloud .INSTANCE_NAME: o nome da instância do Spanner.DATABASE_NAME: o nome do banco de dados do Spanner.DIALECT_NAME: seu dialeto SQL do Spanner. Aceitagooglesqloupostgresql. Se você não especificar um dialeto, o padrão serágooglesql.
Conectar-se ao Spanner no VS Code usando a extensão Data Agent Kit
Com a extensão do Google Cloud Data Agent Kit, é possível gerenciar seu banco de dados do Spanner e executar consultas nos dados do Spanner no IDE de sua preferência. O Visual Studio Code e todos os ambientes de desenvolvimento integrado baseados nele são compatíveis.
Essa extensão oferece recursos de descoberta e análise de dados, permitindo que você faça perguntas sobre seus dados do Spanner em linguagem natural. Ele ajuda a eliminar a troca de contexto entre as ferramentas de linha de comando do Spanner e seu ambiente de desenvolvimento. O Data Agent Kit também fornece plug-ins da CLI para usar com seus recursos do Google Cloud .
Para mais informações, consulte Visão geral da extensão do Data Agent Kit para VS Code.