Gmail AutoAuth MCP Server

Permite que assistentes de IA gerenciem o Gmail por meio de interações em linguagem natural.

GitHubExperimente este MCPPatrocinado

Documentação

Servidor MCP Gmail AutoAuth

Um servidor Model Context Protocol (MCP) para integração com Gmail no Claude Desktop com suporte a autenticação automática. Este servidor permite que assistentes de IA gerenciem o Gmail por meio de interações em linguagem natural.

smithery badge

Recursos

  • Envio de e-mails com assunto, conteúdo, anexos e destinatários
  • Suporte completo para caracteres internacionais em linhas de assunto e conteúdo de e-mail
  • Leitura de mensagens de e-mail por ID com tratamento avançado de estrutura MIME
  • Visualização de informações de anexos de e-mail (nomes de arquivo, tipos, tamanhos)
  • Pesquisa de e-mails com vários critérios (assunto, remetente, intervalo de datas)
  • Gerenciamento abrangente de rótulos com capacidade de criar, atualizar, excluir e listar rótulos
  • Listagem de todos os rótulos disponíveis do Gmail (do sistema e definidos pelo usuário)
  • Listagem de e-mails na caixa de entrada, enviados ou rótulos personalizados
  • Marcação de e-mails como lidos/não lidos
  • Movimentação de e-mails para diferentes rótulos/pastas
  • Exclusão de e-mails
  • Operações em lote para processar eficientemente vários e-mails de uma vez
  • Integração completa com a API do Gmail
  • Fluxo de autenticação OAuth2 simples com abertura automática do navegador
  • Suporte para credenciais de aplicativos Desktop e Web
  • Armazenamento global de credenciais para conveniência

Instalação e Autenticação

Instalação via Smithery

Para instalar o Gmail AutoAuth para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @raghavared/gmail-mcp --client claude

Instalação Manual

  1. Crie um projeto no Google Cloud e obtenha as credenciais:

    a. Crie um projeto no Google Cloud:

    • Acesse o Console do Google Cloud
    • Crie um novo projeto ou selecione um existente
    • Ative a API do Gmail para o seu projeto

    b. Crie as Credenciais OAuth 2.0:

    • Acesse "APIs e Serviços" > "Credenciais"
    • Clique em "Criar Credenciais" > "ID do cliente OAuth"
    • Escolha "Aplicativo para desktop" ou "Aplicativo web" como tipo de aplicativo
    • Dê um nome e clique em "Criar"
    • Para aplicativo web, adicione http://localhost:3000/v2/auth/google/callback aos URIs de redirecionamento autorizados
    • Baixe o arquivo JSON das chaves OAuth do seu cliente
    • Renomeie o arquivo de chave para token.json

  2. Execute a Autenticação:

    Você pode autenticar de duas maneiras:

    a. Autenticação Global (Recomendada):

    # First time: Place token.json in your home directory's .gmail-mcp folder
mkdir -p ~/.gmail-mcp
mv token.json ~/.gmail-mcp/

# Run authentication from anywhere
npx @raghavared/gmail-mcp auth

    b. Autenticação Local:

    # Place token.json in your current directory
# The file will be automatically copied to global config
npx @raghavared/gmail-mcp auth

    O processo de autenticação irá:

    • Procurar por token.json no diretório atual ou em ~/.gmail-mcp/
    • Se encontrado no diretório atual, copiá-lo para ~/.gmail-mcp/
    • Abrir seu navegador padrão para autenticação do Google
    • Salvar as credenciais como ~/.gmail-mcp/credentials.json

    Nota:

    • Após a autenticação bem-sucedida, as credenciais são armazenadas globalmente em ~/.gmail-mcp/ e podem ser usadas de qualquer diretório
    • Credenciais de aplicativos Desktop e Web são suportadas
    • Para credenciais de aplicativo web, certifique-se de adicionar http://localhost:3000/v2/auth/google/callback aos seus URIs de redirecionamento autorizados

  3. Configure no Claude Desktop:

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "@raghavared/gmail-mcp"
      ]
    }
  }
}

Suporte a Docker

Se você preferir usar Docker:

  1. Autenticação:
docker run -i --rm \
  --mount type=bind,source=/path/to/token.json,target=/token.json \
  -v gmail-mcp:/gmail-server \
  -e GMAIL_OAUTH_PATH=/token.json \
  -e "GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json" \
  -p 3000:3000 \
  mcp/gmail auth
  1. Uso:
{
  "mcpServers": {
    "gmail": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "mcp-gmail:/gmail-server",
        "-e",
        "GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json",
        "gmail-mcp"
      ]
    }
  }
}

Autenticação em Servidor na Nuvem

Para ambientes de servidor na nuvem (como n8n), você pode especificar uma URL de callback personalizada durante a autenticação:

npx @raghavared/gmail-mcp auth {domain}/v2/auth/google/callback

Instruções de Configuração para Ambiente na Nuvem

  1. Configure o Proxy Reverso:

    • Configure seu contêiner n8n para expor uma porta para autenticação
    • Configure um proxy reverso para encaminhar o tráfego do seu domínio (ex.: domain.com) para esta porta

  2. Configuração de DNS:

    • Adicione um registro A nas configurações de DNS para resolver seu domínio para o endereço IP do seu servidor na nuvem

  3. Configuração do Google Cloud Platform:

    • No Console do Google Cloud, adicione a URL de callback do seu domínio personalizado (ex.: https://domain.com/v2/auth/google/callback) à lista de URIs de redirecionamento autorizados

  4. Execute a Autenticação:

    npx @raghavared/gmail-mcp auth https://domain.com/v2/auth/google/callback

  5. Configure no seu aplicativo:

    {
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "@raghavared/gmail-mcp"
      ]
    }
  }
}

Essa abordagem permite que os fluxos de autenticação funcionem corretamente em ambientes onde o localhost não é acessível, como aplicativos em contêineres ou servidores na nuvem.

Ferramentas Disponíveis

O servidor fornece as seguintes ferramentas que podem ser usadas através do Claude Desktop:

1. Enviar E-mail (send_email)

Envia um novo e-mail imediatamente.

{
  "to": ["recipient@example.com"],
  "subject": "Meeting Tomorrow",
  "body": "Hi,\n\nJust a reminder about our meeting tomorrow at 10 AM.\n\nBest regards",
  "cc": ["cc@example.com"],
  "bcc": ["bcc@example.com"]
}

2. Rascunho de E-mail (draft_email)

Cria um rascunho de e-mail sem enviá-lo.

{
  "to": ["recipient@example.com"],
  "subject": "Draft Report",
  "body": "Here's the draft report for your review.",
  "cc": ["manager@example.com"]
}

3. Ler E-mail (read_email)

Recupera o conteúdo de um e-mail específico pelo seu ID.

{
  "messageId": "182ab45cd67ef"
}

4. Pesquisar E-mails (search_emails)

Pesquisa e-mails usando a sintaxe de pesquisa do Gmail.

{
  "query": "from:sender@example.com after:2024/01/01 has:attachment",
  "maxResults": 10
}

5. Modificar E-mail (modify_email)

Adiciona ou remove rótulos de e-mails (mover para diferentes pastas, arquivar, etc.).

{
  "messageId": "182ab45cd67ef",
  "addLabelIds": ["IMPORTANT"],
  "removeLabelIds": ["INBOX"]
}

6. Excluir E-mail (delete_email)

Exclui permanentemente um e-mail.

{
  "messageId": "182ab45cd67ef"
}

7. Listar Rótulos de E-mail (list_email_labels)

Recupera todos os rótulos disponíveis do Gmail.

{}

8. Criar Rótulo (create_label)

Cria um novo rótulo no Gmail.

{
  "name": "Important Projects",
  "messageListVisibility": "show",
  "labelListVisibility": "labelShow"
}

9. Atualizar Rótulo (update_label)

Atualiza um rótulo existente do Gmail.

{
  "id": "Label_1234567890",
  "name": "Urgent Projects",
  "messageListVisibility": "show",
  "labelListVisibility": "labelShow"
}

10. Excluir Rótulo (delete_label)

Exclui um rótulo do Gmail.

{
  "id": "Label_1234567890"
}

11. Obter ou Criar Rótulo (get_or_create_label)

Obtém um rótulo existente pelo nome ou o cria se não existir.

{
  "name": "Project XYZ",
  "messageListVisibility": "show",
  "labelListVisibility": "labelShow"
}

12. Modificar E-mails em Lote (batch_modify_emails)

Modifica rótulos de vários e-mails em lotes eficientes.

{
  "messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
  "addLabelIds": ["IMPORTANT"],
  "removeLabelIds": ["INBOX"],
  "batchSize": 50
}

13. Excluir E-mails em Lote (batch_delete_emails)

Exclui permanentemente vários e-mails em lotes eficientes.

{
  "messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
  "batchSize": 50
}

Sintaxe Avançada de Pesquisa

A ferramenta search_emails suporta os poderosos operadores de pesquisa do Gmail:

OperadorExemploDescrição
from:from:john@example.comE-mails de um remetente específico
to:to:mary@example.comE-mails enviados para um destinatário específico
subject:subject:"meeting notes"E-mails com texto específico no assunto
has:attachmenthas:attachmentE-mails com anexos
after:after:2024/01/01E-mails recebidos após uma data
before:before:2024/02/01E-mails recebidos antes de uma data
is:is:unreadE-mails com um estado específico
label:label:workE-mails com um rótulo específico

Você pode combinar vários operadores: from:john@example.com after:2024/01/01 has:attachment

Recursos Avançados

Extração de Conteúdo de E-mail

O servidor extrai inteligentemente o conteúdo de e-mail de estruturas MIME complexas:

  • Prioriza conteúdo em texto simples quando disponível
  • Recorre ao conteúdo HTML se o texto simples não estiver disponível
  • Lida com mensagens MIME de múltiplas partes com partes aninhadas
  • Processa informações de anexos (nome do arquivo, tipo, tamanho)
  • Preserva os cabeçalhos originais do e-mail (De, Para, Assunto, Data)

Suporte a Caracteres Internacionais

O servidor suporta totalmente caracteres não-ASCII em assuntos e conteúdos de e-mail, incluindo:

  • Alfabetos turco, chinês, japonês, coreano e outros não latinos
  • Caracteres especiais e símbolos
  • Codificação adequada garante exibição correta nos clientes de e-mail

Gerenciamento Abrangente de Rótulos

O servidor fornece um conjunto completo de ferramentas para gerenciar rótulos do Gmail:

  • Criar Rótulos: Crie novos rótulos com configurações de visibilidade personalizáveis
  • Atualizar Rótulos: Renomeie rótulos ou altere suas configurações de visibilidade
  • Excluir Rótulos: Remova rótulos criados pelo usuário (rótulos do sistema são protegidos)
  • Encontrar ou Criar: Obtenha um rótulo pelo nome ou crie-o automaticamente se não for encontrado
  • Listar Todos os Rótulos: Veja todos os rótulos do sistema e do usuário com informações detalhadas
  • Opções de Visibilidade de Rótulos: Controle como os rótulos aparecem nas listas de mensagens e rótulos

As configurações de visibilidade de rótulos incluem:

  • messageListVisibility: Controla se o rótulo aparece na lista de mensagens (show ou hide)
  • labelListVisibility: Controla como o rótulo aparece na lista de rótulos (labelShow, labelShowIfUnread ou labelHide)

Esses recursos de gerenciamento de rótulos permitem uma organização sofisticada de e-mails diretamente pelo Claude, sem precisar alternar para a interface do Gmail.

Operações em Lote

O servidor inclui capacidades eficientes de processamento em lote:

  • Processa até 50 e-mails por vez (tamanho de lote configurável)
  • Divisão automática de grandes conjuntos de e-mails para evitar limites da API
  • Relatórios detalhados de sucesso/falha para cada operação
  • Tratamento gracioso de erros com novas tentativas individuais
  • Perfeito para gerenciamento em massa da caixa de entrada e tarefas de organização

Notas de Segurança

  • As credenciais OAuth são armazenadas com segurança no seu ambiente local (~/.gmail-mcp/)
  • O servidor usa acesso offline para manter autenticação persistente
  • Nunca compartilhe ou envie suas credenciais para controle de versão
  • Revise e revogue regularmente acessos não utilizados nas configurações da sua conta Google
  • As credenciais são armazenadas globalmente, mas são acessíveis apenas pelo usuário atual

Solução de Problemas

  1. Chaves OAuth Não Encontradas

    • Certifique-se de que token.json esteja no seu diretório atual ou em ~/.gmail-mcp/
    • Verifique as permissões do arquivo

  2. Formato de Credenciais Inválido

    • Certifique-se de que seu arquivo de chaves OAuth contenha credenciais web ou installed
    • Para aplicativos web, verifique se o URI de redirecionamento está configurado corretamente

  3. Porta Já em Uso

    • Se a porta 3000 já estiver em uso, libere-a antes de executar a autenticação
    • Você pode encontrar e interromper o processo que usa essa porta

  4. Falhas em Operações em Lote

    • Se as operações em lote falharem, elas tentam automaticamente itens individuais novamente
    • Verifique as mensagens de erro detalhadas para falhas específicas
    • Considere reduzir o tamanho do lote se encontrar limitação de taxa

Contribuições

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Licença

MIT

Suporte

Se você encontrar problemas ou tiver dúvidas, por favor, abra uma issue no repositório do GitHub.