Gmail MCP Server

Permite que agentes de IA pesquisem threads do Gmail, aprendam seu estilo de escrita e rascunhem e-mails.

GitHub
22
Experimente este MCPPatrocinado

Documentação

Servidor MCP do Gmail

Um servidor MCP que permite que agentes de IA pesquisem conversas do Gmail, entendam seu estilo de escrita de e-mails e criem rascunhos de e-mails.

1. Obter Autenticação do Google

Passo 1: Criar um Projeto no Google Cloud

  1. Acesse o Console do Google Cloud
  2. Clique no menu suspenso "Selecionar um projeto" no topo
  3. Clique em "Novo Projeto"
  4. Digite um nome para o projeto (ex.: "Gmail MCP Server")
  5. Clique em "Criar"

Passo 2: Ativar a API do Gmail

  1. No seu novo projeto, vá em "APIs e Serviços" → "Biblioteca"
  2. Pesquise por "Gmail API"
  3. Clique em "Gmail API" e depois em "Ativar"

Passo 3: Criar Credenciais OAuth2

  1. Vá em "APIs e Serviços" → "Credenciais"
  2. Clique em "Criar Credenciais" → "ID do Cliente OAuth"
  3. Se solicitado, configure a tela de consentimento OAuth:
    • Escolha o tipo de usuário "Externo"
    • Preencha os campos obrigatórios (Nome do aplicativo, E-mail de suporte ao usuário, E-mail do desenvolvedor)
    • Adicione seu e-mail na seção "Usuários de teste"
    • Salve e continue por todas as etapas
  4. De volta em Credenciais, clique em "Criar Credenciais" → "ID do Cliente OAuth"
  5. Escolha "Aplicativo para desktop" como tipo de aplicativo
  6. Digite um nome (ex.: "Gmail MCP Client")
  7. Clique em "Criar"
  8. Importante: Copie o ID do Cliente e o Segredo do Cliente da caixa de diálogo de confirmação (você precisará deles para a configuração)

Passo 4: Conceder Escopos OAuth

Na primeira execução do servidor, ele abrirá seu navegador para autorização. O servidor solicita apenas estas permissões mínimas:

O Que Solicitamos:

  • ✅ Acesso Somente Leitura ao Gmail (gmail.readonly)

    • Pesquisar e ler suas mensagens de e-mail
    • Baixar anexos de e-mail
    • Visualizar metadados de e-mail (assuntos, remetentes, datas)

  • ✅ Acesso de Composição do Gmail (gmail.compose)

    • Criar rascunhos de e-mail
    • Atualizar rascunhos existentes
    • Excluir rascunhos
    • Enviar e-mails (permissão concedida, mas não usada por este servidor)

O Que Este Servidor Realmente Implementa:

  • ✅ Pesquisar e ler e-mails - Recursos completos de pesquisa
  • ✅ Extrair texto de anexos - Extração segura de texto de PDF/DOCX/TXT
  • ✅ Criar/atualizar rascunhos - Gerenciamento inteligente de rascunhos com consciência de conversas
  • ❌ Enviar e-mails - O servidor não implementa envio (embora a permissão seja concedida)
  • ❌ Excluir e-mails - O servidor não implementa exclusão
  • ❌ Modificar rótulos - O servidor não implementa gerenciamento de rótulos

2. Adicionar aos Clientes MCP

Compile o servidor primeiro: go build .

Você vai querer adicionar isso ao arquivo de configuração do seu agente:

{
  "mcpServers": {
    "gmail": {
      "command": "C:/path/to/your/auto-gmail.exe",
      "env": {
        "GMAIL_CLIENT_ID": "your_client_id_here.apps.googleusercontent.com",
        "GMAIL_CLIENT_SECRET": "your_client_secret_here",
        "OPENAI_API_KEY": "your_openai_api_key_here"
      }
    }
  }
}

⚡ Modo HTTP Persistente (Recomendado para Evitar Pop-ups OAuth)

Problema: No modo stdio, o Cursor inicia um novo processo do servidor a cada vez (e para cada aba), causando spam de pop-ups OAuth.

Solução: Execute o servidor como um daemon HTTP persistente que autentica uma vez e permanece em execução.

Início Rápido:

# Build the server
go build -o gmail-mcp-server

# Start persistent server (OAuth only once!)
./gmail-mcp-server --http

# Or with custom port
./gmail-mcp-server --http 3000

O Que Acontece:

  1. ✅ O pop-up OAuth aparece UMA VEZ quando o servidor inicia
  2. ✅ O servidor executa de forma persistente em http://localhost:8080
  3. ✅ Sem mais pop-ups OAuth - o servidor permanece autenticado
  4. ✅ Várias abas/janelas do Cursor podem se conectar ao mesmo servidor

Configuração do Cursor (Ainda Use stdio por Enquanto):

{
  "mcpServers": {
    "gmail": {
      "command": "C:/path/to/your/gmail-mcp-server",
      "env": {
        "GMAIL_CLIENT_ID": "your_client_id_here.apps.googleusercontent.com", 
        "GMAIL_CLIENT_SECRET": "your_client_secret_here",
        "OPENAI_API_KEY": "your_openai_api_key_here"
      }
    }
  }
}

A diferença: Você inicia o servidor manualmente uma vez em vez de deixar o Cursor iniciá-lo do zero a cada vez.

Status do Servidor:

Adicionar ao Cursor

  • Pressione Ctrl+Shift+P (Windows/Linux) ou Cmd+Shift+P (Mac)
  • Clique na aba MCP
  • Clique em '+ Adicionar novo servidor MCP global'
  • Edite o arquivo de configuração

Adicionar ao Claude Desktop

  • Vá em Arquivo > Configurações > Desenvolvedor > Editar Configuração
  • Edite o arquivo de configuração

Alternativa de Configuração Manual:

Você pode editar esses arquivos de configuração diretamente se souber onde encontrá-los:

  • Cursor: C:\Users\[User]\.cursor\mcp.json
  • Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json (Windows)

3. Ferramentas e Recursos MCP

Ferramentas:

  • search_threads - Pesquise no Gmail com consultas como "de:email@exemplo.com" ou "assunto:reunião" (inclui informações de rascunho)
  • create_draft - Crie rascunhos de e-mail ou atualize rascunhos existentes (a IA solicitará o guia de estilo primeiro)
  • extract_attachment_by_filename - Extraia texto com segurança de anexos PDF, DOCX e TXT usando o nome do arquivo
  • get_personal_email_style_guide - Obtenha seu guia de estilo de escrita de e-mail (esta é uma ferramenta temporária, criada porque a maioria dos agentes ainda não suporta a busca de recursos—quando os agentes implementarem melhor os recursos MCP, esta ferramenta poderá ser removida)

Recursos:

  • file://personal-email-style-guide - Seu estilo pessoal de escrita de e-mail (gerado automaticamente ou manual)

Prompts:

  • /generate-email-tone - Analise seus e-mails enviados para criar um estilo de escrita personalizado
  • /server-status - Mostre locais de arquivos e status do servidor

4. Guia de Estilo Pessoal de E-mail

O servidor criará um arquivo de guia de estilo com base nos últimos 25 e-mails que você enviou, para que os rascunhos de e-mail recém-criados soem como você. Sinceramente, até agora os e-mails escritos por LLM ainda não soam muito autênticos.

Geração Manual:

  • Execute o prompt /generate-email-tone no seu cliente MCP a qualquer momento para regenerar
  • O arquivo é salvo no diretório de dados do seu aplicativo (veja Locais de Armazenamento de Arquivos acima)

Integração com IA:

  • A IA sempre chama a ferramenta get_personal_email_style_guide antes de escrever e-mails
  • Garante estilo pessoal consistente em todas as comunicações
  • Recurso também disponível em file://personal-email-style-guide

5. Maneira Alternativa de Configurar Variáveis de Ambiente

Se você quiser executar este servidor MCP fora de um agente, pode criar um arquivo .env baseado no arquivo .env.example e fornecer as variáveis de ambiente dessa forma, ou exportá-las para o seu ambiente antes de executar:

export GMAIL_CLIENT_ID=your_client_id_here.apps.googleusercontent.com
export GMAIL_CLIENT_SECRET=your_client_secret_here
export OPENAI_API_KEY=your_openai_api_key_here

6. Locais de Armazenamento de Arquivos

O servidor armazena arquivos de autenticação e configuração em diretórios padrão de aplicativos:

Locais de Arquivos:

  • Windows: C:\Users\[YourUsername]\AppData\Roaming\auto-gmail\
  • Mac: ~/.auto-gmail/
  • Linux: ~/.auto-gmail/

Arquivos Importantes:

  • token.json - Token de autenticação OAuth (gerado automaticamente)
  • personal-email-style-guide.md - Seu guia de estilo de escrita de e-mail (gerado automaticamente ou manual)

Comandos Rápidos:

  • Use /server-status no seu cliente MCP para ver os caminhos exatos dos arquivos
  • Exclua token.json para forçar a reautenticação com permissões atualizadas

7. Tarefas Pendentes

  • Melhorar o fluxo de login OAuth - ✅ RESOLVIDO! Use o modo HTTP persistente (./gmail-mcp-server --http) para evitar pop-ups OAuth. O servidor autentica uma vez e permanece em execução.
  • Transporte MCP HTTP Completo - Aguardando o mark3labs/mcp-go expor APIs completas de transporte HTTP
  • Melhor Autenticidade de E-mail - E-mails escritos por LLM ainda não soam perfeitamente autênticos apesar dos guias de estilo