mcp-google-gmail

Gmail MCP

English | Русский

A1 Gmail MCP permite que um aplicativo de IA trabalhe com sua caixa de entrada do Gmail em linguagem natural. Pesquise e leia e-mails, prepare respostas como rascunhos, envie-os quando estiver pronto, mantenha os rótulos organizados e use a lixeira em vez de exclusão permanente.

Ele usa a API do Gmail com sua conta do Google. Ele distingue um rascunho que você ainda pode editar de um e-mail enviado que não pode ser recuperado, e torna explícitos os limites da API do Gmail, em vez de sugerir que toda tarefa de e-mail é reversível.

• 24 ferramentas. Pesquise e leia mensagens e conversas, envie e-mails diretamente ou por rascunhos, gerencie o ciclo de vida dos rascunhos, rótulos e a lixeira.
• Conecta-se a partir da conversa. Diga "conectar Gmail": o servidor guia você pelo cliente OAuth, captura o redirecionamento do Google em 127.0.0.1 com PKCE e mantém os tokens ele mesmo — sem arquivos de configuração, sem reiniciar.
• Envie deliberadamente. O caminho rascunho → revisão → envio é de primeira classe; o envio é marcado como destrutivo, e o servidor nunca reenvia após uma falha ambígua — um e-mail não pode ser "não enviado".
• A lixeira é a rede de segurança. A remoção de e-mails passa pela lixeira reversível (cerca de 30 dias); deliberadamente não existe ferramenta de exclusão permanente de mensagens.
• Leitura limitada. Corpos decodificados são truncados em um limite explícito e anexos retornam como metadados, para que um boletim informativo longo não inunde silenciosamente a conversa.
• Escopo mínimo do Google. Usa apenas gmail.modify — sem exclusão permanente e sem acesso às configurações do Gmail.

Comece com uma pergunta somente de leitura:

Mostre meus e-mails não lidos da última semana e diga quais precisam de resposta.

Conectar o servidor · Explorar casos de uso · Abrir documentação técnica

Veja funcionando em um minuto

Você: O que está não lido na minha caixa de entrada desta semana sobre o contrato da Acme?

Assistente: Pesquisa com a sintaxe de consulta do Gmail e mostra remetentes, assuntos, datas e trechos. Nada é alterado.

Você: Rascunhe uma resposta para o mais recente: enviamos a cópia assinada na sexta-feira.

Assistente: Cria um rascunho na mesma conversa e o exibe para revisão. Nada é enviado.

Você: Envie.

Assistente: Envia o rascunho. O envio é uma etapa separada e explicitamente destrutiva, então seu aplicativo de IA pode pedir confirmação antes.

Conteúdo

• Início rápido
• O que você pode pedir para fazer
• Como os e-mails mudam
• O que pode mudar
• Obtendo acesso
• Configuração
• Dados, limites e trabalho em segundo plano
• Documentação técnica
• Suporte

Início rápido

Você precisa do Node.js 20+ e de uma conta do Google. Credenciais não são necessárias na instalação — o servidor conecta-se a partir da conversa.

1. Adicione o servidor ao seu aplicativo de IA.
2. Diga "conectar Gmail": o assistente guia você pela criação do cliente OAuth e aprovação do acesso sem editar arquivos de configuração.
3. Faça a pergunta somente de leitura acima.

codex mcp add google-gmail \
  -- npx -y mcp-google-gmail@latest

codex mcp list

claude mcp add \
  --transport stdio --scope user google-gmail \
  -- npx -y mcp-google-gmail@latest

claude mcp list

{
  "mcpServers": {
    "google-gmail": {
      "command": "npx",
      "args": ["-y", "mcp-google-gmail@latest"]
    }
  }
}

{
  "mcpServers": {
    "google-gmail": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-gmail@latest"]
    }
  }
}

{
  "servers": {
    "google-gmail": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-gmail@latest"]
    }
  }
}

O que você pode pedir para fazer

Triagem da caixa de entrada

• Mostre mensagens não lidas dos últimos sete dias e agrupe-as por remetente.
• Encontre a conversa com a Acme sobre o contrato e resuma-a, do mais antigo ao mais recente.
• Quais mensagens têm anexos esperando por mim? Mostre assuntos e nomes de arquivos.

Escrever e enviar e-mails

• Rascunhe uma resposta nesta conversa dizendo que a cópia assinada sai na sexta-feira.
• Mostre-me o rascunho, ajuste o texto e depois envie.
• Envie um e-mail curto de status para a equipe, com o gerente em cópia (CC).

Manter a caixa de entrada organizada

• Crie um rótulo Receipts/2026 e aplique-o às mensagens correspondentes.
• Marque os boletins informativos desta semana como lidos e arquive-os.
• Mova essa conversa para a lixeira — e restaure-a se eu mudar de ideia.

Como os e-mails mudam

1. O caminho seguro para o envio é um rascunho: create_draft prepara o e-mail, get_draft o exibe para revisão, send_draft o envia. send_message pula o rascunho e envia imediatamente.
2. Um e-mail enviado é externamente irreversível. Após um tempo limite ou um erro 5xx, o servidor não reenvia; pesquise in:sent antes de tentar novamente, porque um reenvio resultaria em um e-mail duplicado.
3. Remover uma mensagem ou conversa significa movê-la para a lixeira. manage_trash é reversível por cerca de 30 dias; deliberadamente não existe ferramenta de exclusão permanente.
4. Rascunhos são a exceção: update_draft substitui o rascunho inteiro (a API não tem edição parcial) e delete_draft é permanente, porque rascunhos pulam a lixeira.

Cada chamada opera em uma única caixa de entrada — a conta que concedeu o token. Corpos decodificados são truncados em um limite configurável com sinalizadores explícitos, e anexos retornam apenas como metadados; o conteúdo dos anexos é buscado através de raw_request deliberadamente.

O que pode mudar

O cliente de IA controla os prompts de confirmação. O servidor marca leituras, gravações e ferramentas destrutivas para que o cliente possa distinguir uma inspeção de uma alteração ao vivo.

Obtendo acesso

O Google Gmail exige OAuth 2.0; uma chave de API não é suficiente. Há duas formas de acesso, e a primeira não precisa de arquivos de configuração.

Conectar pelo chat (recomendado)

Diga "conectar Gmail" e o assistente executa o fluxo com você:

1. setup_instructions imprime a lista de verificação: crie ou selecione um projeto do Google Cloud, ative a API Gmail, configure a tela de consentimento e crie um cliente OAuth de Aplicativo para desktop.
2. Baixe o JSON desse cliente ("Baixar JSON") e dê ao assistente o caminho — set_client o armazena com acesso apenas do proprietário. O segredo nunca passa pela conversa.
3. start_login retorna um link de consentimento do Google. Abra-o nesta máquina e aprove; o código volta para um ouvinte de uso único em 127.0.0.1 (PKCE), nunca pelo chat.
4. finish_login troca o código e salva os tokens em ~/.config/mcp-google-gmail/credentials.json (modo 0600) e os verifica com uma chamada real à API do Gmail — assim, uma API ainda desativada é detectada ali mesmo.

Os tokens são relidos a cada chamada, então a conexão funciona imediatamente — sem reiniciar o aplicativo de IA. auth_status mostra o que está conectado, logout revoga e exclui.

Variáveis de ambiente (CI, instalações não assistidas)

1. Crie ou selecione um projeto do Google Cloud e ative a API Gmail.

2. Configure a tela de consentimento OAuth e crie um cliente OAuth de Aplicativo para desktop.

3. Autorize a conta do Google cuja caixa de entrada você deseja conectar — cada chamada opera nessa única caixa de entrada. O Playground OAuth 2.0 pode obter o token de atualização quando Usar suas próprias credenciais OAuth estiver ativado.

4. Solicite o escopo:

   https://www.googleapis.com/auth/gmail.modify
   

   Ele cobre pesquisa, leitura, envio, rascunhos, rótulos e a lixeira — mas não exclusão permanente e não configurações do Gmail. Exclusão permanente através de raw_request adicionalmente exige o escopo completo https://mail.google.com/.

Tokens de atualização OAuth em modo de teste podem expirar após sete dias. Publique o aplicativo OAuth, ou use um aplicativo Interno em um domínio do Workspace, quando precisar de acesso de longa duração. Trate o segredo do cliente e o token de atualização como senhas.

Configuração

Todas as variáveis são opcionais — sem nenhuma delas, o servidor conecta-se pelo chat.

* Forneça o trio OAuth ou um token de acesso.

Dados, limites e trabalho em segundo plano

• As solicitações vão para o Gmail. O servidor local atualiza os tokens OAuth do Google e chama a API do Gmail. Sua telemetria anônima contém um ID de instalação, versão do pacote, cliente de IA e versões de plataforma, e nomes de ferramentas — nunca tokens OAuth, conteúdo de e-mail, argumentos de ferramentas ou prompts. Defina ASKADS_TELEMETRY=0 para optar por não participar.
• O Google mede unidades de cota. O Gmail permite cerca de 250 unidades de cota por segundo por usuário; um envio custa 100 unidades, uma leitura típica custa 5. Contas de consumidor podem enviar cerca de 500 e-mails por dia, contas do Workspace cerca de 2.000. Em 429, o servidor usa backoff; leituras também tentam novamente após erros de rede e 5xx, enquanto envios e outras gravações nunca são repetidos após uma falha incerta.
• Não há sondagem em segundo plano. O servidor executa apenas quando chamado. Se seu aplicativo de IA suportar tarefas agendadas, ele pode verificar a caixa de entrada periodicamente; raw_request também pode acessar history.list para sincronização incremental.

Documentação técnica

• Catálogo de capacidades do MCP — páginas orientadas a tarefas para cada ferramenta.
• Todas as ferramentas e entradas
• Documentação de desenvolvimento
• Documentação de publicação
• Referência da API do Gmail

Suporte

Encontrou um bug ou precisa de um cenário? Crie uma issue ou escreva no Telegram.

Você chegou ao final!