Configurar o servidor MCP do Gmail

O Gmail oferece um servidor Protocolo de Contexto de Modelo (MCP) remoto que permite que agentes de IA interajam com segurança com os dados do Gmail. Ao configurar o servidor MCP do Gmail, você permite que aplicativos de IA, como o Google Antigravity e o Claude, realizem ações no Gmail.

O servidor MCP do Gmail oferece uma maneira padronizada para que os agentes de IA:

  • Ler dados: pesquisar e-mails, recuperar conversas e listar marcadores.
  • Entre em ação: crie rascunhos de e-mail e rotule mensagens.
  • Respeitar a segurança: herdar as mesmas permissões e controles de governança de dados do usuário.

Pré-requisitos

Configurar o servidor MCP do Gmail

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

Ative as APIs

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

  • API Gmail

CLI

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

Substitua PROJECT_ID pelo ID do projeto do Google Cloud.

Console

Ative as APIs no console do Google Cloud:

Ativar as APIs

Ativar os serviços do MCP

Para ativar os componentes do MCP no Gmail, é necessário ativar o seguinte serviço no projeto do Google Cloud:

  • API Gmail MCP

CLI

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

Substitua PROJECT_ID pelo ID do projeto do Google Cloud.

Console

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

Ativar os serviços do MCP

O servidor MCP do Gmail 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 plataforma de autenticação do Google, poderá configurar as seguintes opções da tela de permissão OAuth em Branding, Público-alvo e Acesso a dados. Se você receber uma mensagem informando que a Plataforma de autenticação do Google ainda não está configurada, clique em Começar:

    1. Em Informações do app, em Nome do app, digite Gmail MCP Server.
    2. Em E-mail para suporte do usuário, selecione seu endereço de e-mail ou um grupo do Google adequado.
    3. Clique em Próxima.
    4. Em Público-alvo, selecione Interno. Se não for possível selecionar Interno, escolha Externo.
    5. Clique em Próxima.
    6. Em Informações de contato, insira um Endereço de e-mail em que você possa receber notificações sobre mudanças no seu projeto.
    7. Clique em Próxima.
    8. Em Concluir, leia 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 como 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. Depois, clique em Salvar.

  3. Clique em Acesso a dados > Adicionar ou remover escopos. Um painel vai aparecer 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 do Gmail:

      • https://www.googleapis.com/auth/gmail.readonly
      • https://www.googleapis.com/auth/gmail.compose

    2. Clique em Adicionar à tabela.

    3. Clique em Atualizar.

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

Configurar o cliente MCP

Para adicionar o servidor MCP remoto do Gmail ao seu cliente MCP, siga as instruções do cliente.

Antigravity

Para adicionar o servidor MCP remoto do Gmail ao Antigravity, adicione a configuração do servidor ao arquivo mcp_config.json. Estas instruções são compatíveis com o Antigravity 2.0, a 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.

      Acesse "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 campo URIs.

    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": {
    "gmail": {
      "serverUrl": "https://gmailmcp.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 fazer a autenticação usando as configurações da GUI ou a CLI:

    • Para o IDE do Antigravity ou a GUI (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. Acesse Personalizações.
      3. Em Servidores MCP instalados, clique em Atualizar.
      4. Encontre gmail 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 interativo de gerenciamento do MCP executando:

        /mcp

      3. Use as teclas de seta para selecionar gmail, vá até a ação Autenticar e pressione Enter. Conclua o fluxo de login no navegador, copie o código de autorização, cole 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 interativo da TUI. Selecione qualquer servidor na visualização do painel para inspecionar o status dele e listar todas as ferramentas disponíveis.

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

Claude

Para usar o servidor MCP remoto do Gmail com o Claude.ai ou o Claude Desktop, você precisa ter o plano Enterprise, Pro, Max ou Team do Claude.

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

  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.

      Acesse "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 para computador, acesse Configurações (ou Configurações de administrador) > Conectores.
    2. Clique em Adicionar conector personalizado.
    3. Insira os detalhes da conexão do produto do Gmail:
      • Nome do servidor: Gmail.
      • URL do servidor MCP remoto: https://gmailmcp.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 do Gmail, insira o seguinte:

  • Nome do servidor: gmail

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

  • Transporte: HTTP

  • Autenticação: o servidor MCP remoto do Gmail usa o OAuth 2.0. Para 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 do Gmail

Depois de configurar o cliente MCP, você pode verificar a conexão executando alguns comandos de teste.

Faça as seguintes perguntas ao cliente do MCP:

  • "O que a Ariel disse no último e-mail sobre nosso plano de marketing?"

    O cliente filtra e-mails de Ariel usando gmail.search_threads, recupera o conteúdo da conversa mais recente com gmail.get_thread e resume para você.

  • "Escreva um e-mail para ariel@example.com dizendo que eu aprovo o plano de marketing."

    O cliente usa gmail.create_draft para criar um e-mail na sua pasta de rascunhos e permitir que você revise e envie pelo Gmail.

Se as ferramentas forem executadas sem problemas e você receber respostas relevantes, o servidor MCP do Gmail 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 do Gmail:

  • create_draft
  • get_thread
  • label_message
  • label_thread
  • list_drafts
  • list_labels
  • search_threads
  • unlabel_message
  • unlabel_thread

Consideração importante sobre segurança: injeção indireta de comando

Quando você expõe um modelo de linguagem a dados não confiáveis, há risco de um ataque de injeção de comando indireto. Como hosts do MCP, como o Google Antigravity, têm acesso a ferramentas e APIs avançadas pelo servidor MCP do Gmail, eles podem ler, modificar e excluir dados na sua Conta do Google.

Para reduzir esses riscos, filtre comandos e respostas em busca de conteúdo malicioso ou ataques de injeção de comandos. Você pode usar o Model Armor fornecido pelo Google ou sua própria solução, desde que a documente para que os usuários aceitem esse risco. Para mais informações, consulte Configurar a segurança dos servidores MCP do Google Workspace.

Siga estas práticas recomendadas:

  • Use apenas ferramentas confiáveis. Nunca conecte o servidor MCP do Gmail a aplicativos não confiáveis ou não verificados.
  • Tenha cuidado com entradas não confiáveis. Evite pedir ao cliente do MCP para processar e-mails 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 com cuidado as ações realizadas pelo seu cliente de IA em seu nome para garantir que estejam corretas e alinhadas às suas intenções.