Configurar o servidor MCP do Planilhas

As Planilhas Google oferecem um servidor de protocolo de contexto de modelo (MCP) remoto que permite que agentes de IA interajam com segurança com os dados das Planilhas Google. Ao configurar o servidor MCP das Planilhas Google, você permite que aplicativos de IA, como o Google Antigravity e o Claude, realizem ações nas Planilhas Google.

O servidor MCP das Planilhas Google oferece uma maneira padronizada para que os agentes de IA possam:

  • Ler dados: recupere valores de células, nomes de planilhas, propriedades de grade e outros metadados de planilhas.
  • Entre em ação: atualize valores de células, defina fórmulas, insira linhas/colunas e execute atualizações em lote estruturais de planilhas.
  • Respeitar a segurança: herde as mesmas permissões e governança de dados controles do usuário.

Pré-requisitos

  • Um projeto do Google Cloud. Para criar um projeto, consulte Criar um projeto.

  • Um cliente MCP, como Google Antigravity.

  • Para executar os comandos nesta página, configure a CLI gcloud em um dos seguintes ambientes de desenvolvimento:

    Cloud Shell

    Para usar um terminal on-line com a CLI gcloud já configurada, ative o Cloud Shell:

    Ativar o Cloud Shell

    Shell local

    Para usar um ambiente de desenvolvimento local, siga estas etapas:

    1. Instale a CLI do Google Cloud. Se você instalou a CLI gcloud anteriormente, verifique se tem a versão mais recente executando gcloud components update.
    2. Se você usa um provedor de identidade (IdP) externo, faça login na CLI gcloud com sua identidade federada. Para mais informações, consulte Fazer login na CLI gcloud com sua identidade federada.
    3. Inicialize a CLI gcloud.

Configurar o servidor MCP das Planilhas Google

Para usar o servidor MCP do Google Planilhas, ative-o no seu projeto na nuvem do Google Cloud e configure o cliente MCP para se conectar a ele.

Ative as APIs

Para usar o servidor MCP das Planilhas Google, ative a seguinte API no seu projeto do Google Cloud:

  • API Google Sheets

CLI

gcloud services enable sheets.googleapis.com --project=PROJECT_ID

Substitua PROJECT_ID pelo ID do projeto do Google Cloud.

Console

Ative as APIs no console do Google Cloud:

Ative as APIs

Ativar os serviços MCP

Para ativar os componentes MCP das Planilhas Google, ative o seguinte serviço no seu projeto do Google Cloud:

  • API MCP das Planilhas Google

CLI

gcloud services enable sheetsmcp.googleapis.com --project=PROJECT_ID

Substitua PROJECT_ID pelo ID do projeto do Google Cloud.

Console

Ative os serviços MCP no console do Google Cloud:

Ativar os serviços MCP

O servidor MCP das Planilhas Google usa o OAuth 2.0 para autenticação e autorização. É necessário configurar a tela de permissão OAuth antes de criar um ID do cliente OAuth.

  1. No console do Google Cloud, acesse Google Auth Platform > Branding.

    Acessar Branding

  2. Se você já tiver configurado a Google Auth Platform, poderá configurar as seguintes definições da tela de permissão OAuth em Branding, Público-alvo, e Acesso a dados. Se você vir uma mensagem informando que a Google Auth Platform ainda não está configurada ainda, clique em Começar:

    1. Em Informações do app, em Nome do app, digite Sheets MCP Server.
    2. Em E-mail de suporte ao usuário, selecione seu endereço de e-mail ou um grupo do Google apropriado.
    3. Clique em Próxima.
    4. Em Público-alvo, selecione Interno. Se não for possível selecionar Interno, selecione Externo.
    5. Clique em Próxima.
    6. Em Informações de contato, insira um endereço de e-mail em que você possa ser notificado sobre mudanças no seu projeto.
    7. Clique em Próxima.
    8. Em Concluir, revise a Política de dados do usuário dos serviços de API do Google e, se concordar, selecione Concordo com a Política de dados do usuário dos serviços de API do Google.
    9. Clique em Continuar.
    10. Clique em Criar.
    11. Se você selecionou Externo para o tipo de usuário, adicione usuários de teste:
      1. Clique em Público-alvo.
      2. Em Usuários de teste, clique em Adicionar usuários.
      3. Insira seu endereço de e-mail e os outros usuários de teste autorizados e clique em Salvar.

  3. Clique em Acesso a dados > Adicionar ou remover escopos. Um painel aparece com uma lista de escopos para cada API ativada no seu projeto do Google Cloud.

    1. Em Adicionar escopos manualmente, cole os escopos do servidor MCP das Planilhas Google:

      • https://www.googleapis.com/auth/drive.readonly
      • https://www.googleapis.com/auth/spreadsheets.readonly

    2. Clique em Adicionar à tabela.

    3. Clique em Atualizar.

    4. Depois de selecionar os escopos exigidos pelo app, na página Acesso a dados, clique em Salvar.

Configurar o cliente MCP

Para adicionar o servidor MCP remoto das Planilhas Google ao cliente MCP, siga as instruções do cliente.

Antigravity

Para adicionar o servidor MCP remoto das Planilhas Google ao Antigravity, adicione a configuração do servidor ao arquivo mcp_config.json. Essas instruções são compatíveis com o Antigravity 2.0, o IDE do Antigravity e a CLI do Antigravity.

  1. Crie um ID do cliente e uma chave secreta do OAuth 2.0:

    1. No console do Google Cloud, acesse Google Auth Platform > Clientes > Criar cliente

      Acessar Criar cliente

    2. Selecione Aplicativo da Web como o tipo de aplicativo.

    3. Digite um Nome.

    4. Na seção URIs de redirecionamento autorizados, clique em + Adicionar URI, e adicione https://antigravity.google/oauth-callback no URIs campo.

    5. Clique em Criar e copie o ID do cliente e a chave secreta do cliente.

  2. Abra ou crie o arquivo de configuração ~/.gemini/antigravity/mcp_config.json.

  3. Adicione a configuração mcpServers a mcp_config.json:

    {
  "mcpServers": {
    "sheets": {
      "serverUrl": "https://sheetsmcp.googleapis.com/mcp/v1",
      "oauth": {
        "clientId": "OAUTH_CLIENT_ID",
        "clientSecret": "OAUTH_CLIENT_SECRET"
      }
    }
  }
}

    Substitua:

    • OAUTH_CLIENT_ID: o ID do cliente que você criou.
    • OAUTH_CLIENT_SECRET: a chave secreta do cliente que você criou.

  4. Economize mcp_config.json.

  5. Autentique o servidor MCP. É possível autenticar usando as configurações da GUI ou a CLI:

    • Para o IDE ou a GUI do Antigravity (Antigravity 2.0) :

      1. Abra a tela de configurações (por exemplo, clique em Configurações no canto inferior esquerdo ou abra Configurações do usuário do Antigravity).
      2. Navegue até Personalizações.
      3. Em Servidores MCP instalados, clique em Atualizar.
      4. Encontre sheets na lista, clique em Autenticar, faça login na sua Conta do Google, copie o código de autorização, cole-o na caixa de diálogo de entrada e clique em Enviar.

    • Para a CLI do Antigravity :

      1. Inicie a CLI do Antigravity:

        agy

      2. Abra o painel de gerenciamento interativo do MCP executando:

        /mcp

      3. Use as teclas de seta para selecionar sheets, vá para a ação Autenticar e pressione Enter. Conclua o fluxo de login no navegador, copie o código de autorização, cole-o no prompt do terminal e pressione Enter.

  6. Verifique se o servidor está configurado e em execução corretamente:

    • Para o IDE ou a GUI do Antigravity:um botão Sair é mostrado ao lado do servidor em Personalizações > Servidores MCP instalados.
    • Para a CLI do Antigravity:abra o painel /mcp para conferir os servidores MCP configurados. Os servidores verificados e autenticados mostram Autenticado ao lado dos nomes no painel TUI interativo. É possível selecionar qualquer servidor na visualização do painel para inspecionar o status e listar todas as ferramentas disponíveis.

O servidor MCP remoto está pronto para uso no Antigravity.

Claude

Para usar o servidor MCP remoto das Planilhas Google com o Claude.ai ou o Claude Desktop, é necessário ter o plano Claude Enterprise, Pro, Max ou Team.

Para adicionar o servidor MCP remoto das Planilhas Google ao Claude, configure um conector personalizado com um ID do cliente OAuth e uma chave secreta.

  1. Crie um ID do cliente e uma chave secreta do OAuth 2.0:

    1. No console do Google Cloud, acesse Google Auth Platform > Clientes > Criar cliente

      Acessar Criar cliente

    2. Selecione Aplicativo da Web como o tipo de aplicativo.

    3. Digite um Nome.

    4. Na seção URIs de redirecionamento autorizados, clique em + Adicionar URI, e adicione https://claude.ai/api/mcp/auth_callback no campo URIs.

    5. Clique em Criar e copie o ID do cliente e a chave secreta do cliente.

  2. Configure o servidor MCP no Claude:

    1. No Claude.ai ou no Claude Desktop, acesse Configurações (ou Configurações de administrador) > Conectores.
    2. Clique em Adicionar conector personalizado.
    3. Insira os detalhes da conexão do produto Planilhas Google:
      • Nome do servidor: Google Sheets.
      • URL do servidor MCP remoto: https://sheetsmcp.googleapis.com/mcp/v1
    4. Em Configurações avançadas, insira o ID do cliente OAuth e a chave secreta do cliente OAuth.
    5. Clique em Adicionar.

Outros

Muitos aplicativos de IA têm maneiras de se conectar a um servidor MCP remoto. Normalmente, é necessário inserir detalhes sobre o servidor, como nome, endpoints, protocolo de transporte e método de autenticação. Para o servidor MCP remoto das Planilhas Google, insira o seguinte:

  • Nome do servidor: sheets

  • URL do servidor: https://sheetsmcp.googleapis.com/mcp/v1

  • Transporte: HTTP

  • Autenticação: o servidor MCP remoto das Planilhas Google usa o OAuth 2.0. Para mais detalhes, consulte Saiba mais sobre autenticação e autorização.

Para mais detalhes sobre como conectar diferentes tipos de clientes, consulte Configurar o MCP em um aplicativo de IA.

Testar o servidor MCP das Planilhas Google

Depois de configurar o cliente MCP, é possível verificar a conexão executando alguns comandos de teste.

Tente fazer as seguintes perguntas ao cliente MCP:

  • "Leia a planilha Sheet1 da Planilha Google abcd123."

    O cliente busca valores de grade usando sheets.get_values.

  • "Insira uma coluna no índice 2 da Planilha Google abcd123."

    O cliente executa sheets.insert_dimension para alterar colunas.

Se as ferramentas forem executadas com sucesso e você receber respostas relevantes, o servidor MCP das Planilhas Google estará configurado corretamente.

Solução de problemas

Se você tiver problemas para se conectar ao servidor MCP, verifique se há erros nos registros do OAuth. Peça ao administrador para verificar os eventos de registro do OAuth na ferramenta de investigação de segurança.

Referência da ferramenta

As seguintes ferramentas estão disponíveis para o servidor MCP das Planilhas Google:

  • get_values
  • get_spreadsheet
  • update_spreadsheet
  • update_values
  • update_formulas
  • insert_dimension

Consideração de segurança importante: injeção indireta de comandos

Quando você expõe um modelo de linguagem a dados não confiáveis, há risco de um ataque de injeção indireta de comandos. Como os clientes MCP, como o Google Antigravity, têm acesso a ferramentas e APIs poderosas pelo servidor MCP das Planilhas Google, eles podem ler, modificar e excluir dados na sua Conta do Google.

Para mitigar esses riscos, siga estas práticas recomendadas:

  • Use apenas ferramentas confiáveis. Nunca conecte o servidor MCP das Planilhas Google a aplicativos não confiáveis ou não verificados.
  • Tenha cuidado com entradas não confiáveis. Evite pedir ao cliente MCP para processar planilhas ou outros recursos de fontes não verificadas. Essas entradas podem conter instruções ocultas que podem sequestrar sua sessão, permitindo que um invasor modifique, roube ou exclua seus dados.
  • Revise todas as ações. Sempre revise cuidadosamente as ações realizadas pelo cliente de IA em seu nome para garantir que elas estejam corretas e alinhadas às suas intenções.