Gmail AutoAuth MCP Server

Um servidor MCP para integrar o Gmail com suporte a autenticação automática.

GitHub
1.2k

Documentação

Gmail AutoAuth MCP Server

Um servidor Model Context Protocol (MCP) para integração com o 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 a anexos - envie e receba arquivos anexados
  • Download de anexos de e-mail para o sistema de arquivos local
  • Suporte a e-mails HTML e mensagens multipartes com versões em HTML e texto simples
  • Suporte completo a caracteres internacionais em linhas de assunto e conteúdo de e-mails
  • Leitura de mensagens de e-mail por ID com tratamento avançado de estrutura MIME
  • Exibição aprimorada de anexos mostrando nomes de arquivo, tipos, tamanhos e IDs de download
  • 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 a 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 @gongrzhe/server-gmail-autoauth-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 Google Cloud Console
    • Crie um novo projeto ou selecione um existente
    • Ative a API do Gmail para o seu projeto

    b. Crie credenciais OAuth 2.0:

    • Acesse "APIs & Services" > "Credentials"
    • Clique em "Create Credentials" > "OAuth client ID"
    • Escolha "Desktop app" ou "Web application" como tipo de aplicativo
    • Dê um nome e clique em "Create"
    • Para aplicativos Web, adicione http://localhost:3000/oauth2callback aos URIs de redirecionamento autorizados
    • Baixe o arquivo JSON com as chaves OAuth do seu cliente
    • Renomeie o arquivo de chave para gcp-oauth.keys.json

  2. Execute a Autenticação:

    Você pode autenticar de duas maneiras:

    a. Autenticação Global (Recomendada):

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

# Run authentication from anywhere
npx @gongrzhe/server-gmail-autoauth-mcp auth

    b. Autenticação Local:

    # Place gcp-oauth.keys.json in your current directory
# The file will be automatically copied to global config
npx @gongrzhe/server-gmail-autoauth-mcp auth

    O processo de autenticação irá:

    • Procurar por gcp-oauth.keys.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 aplicativos Web, certifique-se de adicionar http://localhost:3000/oauth2callback aos seus URIs de redirecionamento autorizados

  3. Configure no Claude Desktop:

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

Suporte a Docker

Se você preferir usar Docker:

  1. Autenticação:
docker run -i --rm \
  --mount type=bind,source=/path/to/gcp-oauth.keys.json,target=/gcp-oauth.keys.json \
  -v mcp-gmail:/gmail-server \
  -e GMAIL_OAUTH_PATH=/gcp-oauth.keys.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",
        "mcp/gmail"
      ]
    }
  }
}

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 @gongrzhe/server-gmail-autoauth-mcp auth https://gmail.gongrzhe.com/oauth2callback

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 (por exemplo, gmail.gongrzhe.com) para esta porta

  2. Configuração de DNS:

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

  3. Configuração no Google Cloud Platform:

    • No seu Google Cloud Console, adicione a URL de callback do seu domínio personalizado (por exemplo, https://gmail.gongrzhe.com/oauth2callback) à lista de URIs de redirecionamento autorizados

  4. Execute a Autenticação:

    npx @gongrzhe/server-gmail-autoauth-mcp auth https://gmail.gongrzhe.com/oauth2callback

  5. Configure no seu aplicativo:

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

Essa abordagem permite que os fluxos de autenticação funcionem corretamente em ambientes onde 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. Suporta e-mails em texto simples, HTML ou multipartes com anexos de arquivo opcionais.

E-mail Básico:

{
  "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"],
  "mimeType": "text/plain"
}

E-mail com Anexos:

{
  "to": ["recipient@example.com"],
  "subject": "Project Files",
  "body": "Hi,\n\nPlease find the project files attached.\n\nBest regards",
  "attachments": [
    "/path/to/document.pdf",
    "/path/to/spreadsheet.xlsx",
    "/path/to/presentation.pptx"
  ]
}

Exemplo de E-mail HTML:

{
  "to": ["recipient@example.com"],
  "subject": "Meeting Tomorrow",
  "mimeType": "text/html",
  "body": "<html><body><h1>Meeting Reminder</h1><p>Just a reminder about our <b>meeting tomorrow</b> at 10 AM.</p><p>Best regards</p></body></html>"
}

Exemplo de E-mail Multiparte (HTML + Texto Simples):

{
  "to": ["recipient@example.com"],
  "subject": "Meeting Tomorrow",
  "mimeType": "multipart/alternative",
  "body": "Hi,\n\nJust a reminder about our meeting tomorrow at 10 AM.\n\nBest regards",
  "htmlBody": "<html><body><h1>Meeting Reminder</h1><p>Just a reminder about our <b>meeting tomorrow</b> at 10 AM.</p><p>Best regards</p></body></html>"
}

2. Rascunho de E-mail (draft_email)

Cria um rascunho de e-mail sem enviá-lo. Também suporta anexos.

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

3. Ler E-mail (read_email)

Recupera o conteúdo de um e-mail específico pelo seu ID. Agora mostra informações aprimoradas de anexos.

{
  "messageId": "182ab45cd67ef"
}

Resposta aprimorada inclui detalhes dos anexos:

Subject: Project Files
From: sender@example.com
To: recipient@example.com
Date: Thu, 19 Jun 2025 10:30:00 -0400

Email body content here...

Attachments (2):
- document.pdf (application/pdf, 245 KB, ID: ANGjdJ9fkTs-i3GCQo5o97f_itG...)
- spreadsheet.xlsx (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, 89 KB, ID: BWHkeL8gkUt-j4HDRp6o98g_juI...)

4. Baixar Anexo (download_attachment)

NOVO: Baixa anexos de e-mail para o seu sistema de arquivos local.

{
  "messageId": "182ab45cd67ef",
  "attachmentId": "ANGjdJ9fkTs-i3GCQo5o97f_itG...",
  "savePath": "/path/to/downloads",
  "filename": "downloaded_document.pdf"
}

Parâmetros:

  • messageId: O ID do e-mail que contém o anexo
  • attachmentId: O ID do anexo (mostrado na exibição aprimorada de e-mail)
  • savePath: Diretório para salvar o arquivo (opcional, padrão é o diretório atual)
  • filename: Nome de arquivo personalizado (opcional, usa o nome original se não for fornecido)

5. 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
}

6. 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"]
}

7. Excluir E-mail (delete_email)

Exclui permanentemente um e-mail.

{
  "messageId": "182ab45cd67ef"
}

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

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

{}

9. Criar Rótulo (create_label)

Cria um novo rótulo do Gmail.

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

10. Atualizar Rótulo (update_label)

Atualiza um rótulo existente do Gmail.

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

11. Excluir Rótulo (delete_label)

Exclui um rótulo do Gmail.

{
  "id": "Label_1234567890"
}

12. 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"
}

13. 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
}

14. Excluir E-mails em Lote (batch_delete_emails)

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

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

14. Criar Filtro (create_filter)

Cria um novo filtro do Gmail com critérios e ações personalizados.

{
  "criteria": {
    "from": "newsletter@company.com",
    "hasAttachment": false
  },
  "action": {
    "addLabelIds": ["Label_Newsletter"],
    "removeLabelIds": ["INBOX"]
  }
}

15. Listar Filtros (list_filters)

Recupera todos os filtros do Gmail.

{}

16. Obter Filtro (get_filter)

Obtém detalhes de um filtro específico do Gmail.

{
  "filterId": "ANe1Bmj1234567890"
}

17. Excluir Filtro (delete_filter)

Exclui um filtro do Gmail.

{
  "filterId": "ANe1Bmj1234567890"
}

18. Criar Filtro a partir de Modelo (create_filter_from_template)

Cria um filtro usando modelos pré-definidos para cenários comuns.

{
  "template": "fromSender",
  "parameters": {
    "senderEmail": "notifications@github.com",
    "labelIds": ["Label_GitHub"],
    "archive": true
  }
}

Recursos de Gerenciamento de Filtros

Critérios de Filtro

Você pode criar filtros com base em vários critérios:

CritérioExemploDescrição
from"sender@example.com"E-mails de um remetente específico
to"recipient@example.com"E-mails enviados para um destinatário específico
subject"Meeting"E-mails com texto específico no assunto
query"has:attachment"Sintaxe de consulta de pesquisa do Gmail
negatedQuery"spam"Texto que NÃO deve estar presente
hasAttachmenttrueE-mails com anexos
size10485760Tamanho do e-mail em bytes
sizeComparison"larger"Comparação de tamanho (larger, smaller)

Ações de Filtro

Os filtros podem executar as seguintes ações:

AçãoExemploDescrição
addLabelIds["IMPORTANT", "Label_Work"]Adicionar rótulos a e-mails correspondentes
removeLabelIds["INBOX", "UNREAD"]Remover rótulos de e-mails correspondentes
forward"backup@example.com"Encaminhar e-mails para outro endereço

Modelos de Filtro

O servidor inclui modelos pré-construídos para cenários comuns de filtragem:

1. Modelo de Remetente (fromSender)

Filtra e-mails de um remetente específico e opcionalmente os arquiva.

{
  "template": "fromSender",
  "parameters": {
    "senderEmail": "newsletter@company.com",
    "labelIds": ["Label_Newsletter"],
    "archive": true
  }
}

2. Modelo de Filtro por Assunto (withSubject)

Filtra e-mails com texto específico no assunto e opcionalmente os marca como lidos.

{
  "template": "withSubject",
  "parameters": {
    "subjectText": "[URGENT]",
    "labelIds": ["Label_Urgent"],
    "markAsRead": false
  }
}

3. Modelo de Filtro por Anexo (withAttachments)

Filtra todos os e-mails com anexos.

{
  "template": "withAttachments",
  "parameters": {
    "labelIds": ["Label_Attachments"]
  }
}

4. Modelo de E-mail Grande (largeEmails)

Filtra e-mails maiores que um tamanho especificado.

{
  "template": "largeEmails",
  "parameters": {
    "sizeInBytes": 10485760,
    "labelIds": ["Label_Large"]
  }
}

5. Modelo de Filtro por Conteúdo (containingText)

Filtra e-mails contendo texto específico e opcionalmente os marca como importantes.

{
  "template": "containingText",
  "parameters": {
    "searchText": "invoice",
    "labelIds": ["Label_Finance"],
    "markImportant": true
  }
}

6. Modelo de Lista de Discussão (mailingList)

Filtra e-mails de listas de discussão e opcionalmente os arquiva.

{
  "template": "mailingList",
  "parameters": {
    "listIdentifier": "dev-team",
    "labelIds": ["Label_DevTeam"],
    "archive": true
  }
}

Exemplos Comuns de Filtro

Aqui estão alguns exemplos práticos de filtros:

Organizar newsletters automaticamente:

{
  "criteria": {
    "from": "newsletter@company.com"
  },
  "action": {
    "addLabelIds": ["Label_Newsletter"],
    "removeLabelIds": ["INBOX"]
  }
}

Lidar com e-mails promocionais:

{
  "criteria": {
    "query": "unsubscribe OR promotional"
  },
  "action": {
    "addLabelIds": ["Label_Promotions"],
    "removeLabelIds": ["INBOX", "UNREAD"]
  }
}

E-mails prioritários do chefe:

{
  "criteria": {
    "from": "boss@company.com"
  },
  "action": {
    "addLabelIds": ["IMPORTANT", "Label_Boss"]
  }
}

Anexos grandes:

{
  "criteria": {
    "size": 10485760,
    "sizeComparison": "larger",
    "hasAttachment": true
  },
  "action": {
    "addLabelIds": ["Label_LargeFiles"]
  }
}

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

Suporte a Anexos de E-mail

O servidor fornece funcionalidade abrangente de anexos:

  • Envio de Anexos: Inclua caminhos de arquivo no array attachments ao enviar ou criar rascunhos de e-mails
  • Detecção de Anexos: Detecta automaticamente tipos MIME e tamanhos de arquivo
  • Capacidade de Download: Baixe qualquer anexo de e-mail para o seu sistema de arquivos local
  • Exibição Aprimorada: Visualize informações detalhadas dos anexos, incluindo nomes de arquivo, tipos, tamanhos e IDs de download
  • Múltiplos Formatos: Suporte a todos os tipos comuns de arquivo (documentos, imagens, arquivos compactados, etc.)
  • Conformidade RFC822: Usa Nodemailer para formatação adequada de mensagens MIME

Tipos de Arquivo Suportados: Todos os tipos de arquivo padrão, incluindo PDF, DOCX, XLSX, PPTX, imagens (PNG, JPG, GIF), arquivos compactados (ZIP, RAR) e mais.

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

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

  • Prioriza o conteúdo em texto simples quando disponível
  • Usa o conteúdo HTML como alternativa se o texto simples não estiver disponível
  • Trata mensagens MIME multipartes com partes aninhadas
  • Processa informações de anexos (nome do arquivo, tipo, tamanho, ID de download)
  • 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údo de e-mails, 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 em 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 de 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 recursos eficientes de processamento em lote:

  • Processe até 50 e-mails de uma vez (tamanho do 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 de caixa de entrada e tarefas de organização em massa

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 a autenticação persistente
  • Nunca compartilhe ou envie suas credenciais para o 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ó podem ser acessadas pelo usuário atual
  • Os arquivos anexos são processados localmente e nunca são armazenados permanentemente pelo servidor

Solução de Problemas

  1. Chaves OAuth não encontradas

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

  2. Formato de credenciais inválido

    • Certifique-se de que o arquivo de chaves OAuth contenha credenciais do tipo web ou installed
    • Para aplicações 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 novamente os itens individuais
    • Verifique as mensagens de erro detalhadas para falhas específicas
    • Considere reduzir o tamanho do lote se encontrar limitação de taxa

  5. Problemas com anexos

    • Arquivo não encontrado: Garanta que os caminhos dos arquivos de anexo estejam corretos e acessíveis
    • Erros de permissão: Verifique se o servidor tem permissão de leitura para os arquivos de anexo
    • Limites de tamanho: O Gmail tem um limite de anexo de 25MB por e-mail
    • Falhas de download: Verifique se você tem permissões de escrita no diretório de download

Contribuindo

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

Executando evals

O pacote de evals carrega um cliente mcp que então executa o arquivo index.ts, então não há necessidade de recompilar entre os testes. Você pode carregar variáveis de ambiente prefixando o comando npx. Documentação completa pode ser encontrada aqui.

OPENAI_API_KEY=your-key  npx mcp-eval src/evals/evals.ts src/index.ts

Licença

MIT

Suporte

Se você encontrar algum problema ou tiver dúvidas, por favor registre uma issue no repositório GitHub.