Gmail MCP Server

Um servidor MCP para interagir com Gmail e Google Calendar, permitindo gerenciamento de e-mails e eventos com consciência de contexto.

GitHub

Documentação

Gmail MCP Server

smithery badge

Um servidor Model Context Protocol (MCP) para integração com Gmail e Google Calendar no Claude Desktop, permitindo interações inteligentes e sensíveis ao contexto com seu e-mail.

🌟 Recursos

  • Análise Profunda de E-mails: Fornece contexto abrangente de conversas inteiras
  • Respostas Sensíveis ao Contexto: Gera respostas considerando todo o histórico de comunicação
  • Sugestões Inteligentes de Ações: Analisa o conteúdo do e-mail para eventos de calendário, tarefas e acompanhamentos
  • Integração com Calendário: Detecta eventos em e-mails e cria entradas de calendário com suporte a linguagem natural
  • Busca Avançada: Pesquisa em todo o histórico de e-mails com compreensão semântica
  • Personalização: Adapta-se ao seu estilo de comunicação com contatos específicos

🚀 Começando

Pré-requisitos

  • Python 3.10+
  • Uma conta no Google Cloud Platform com a API do Gmail e a API do Google Calendar (opcional) habilitadas
  • Credenciais OAuth 2.0 para a API do Gmail e a API do Google Calendar (opcional)
  • Claude Desktop com suporte a MCP (atualmente, a única interface LLM com suporte a MCP)

Instalação

Instalando via Smithery

Para instalar automaticamente o Gmail Integration Server para Claude Desktop via Smithery:

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

Instalação Manual

  1. Clone este repositório:

    git clone https://github.com/bastienchabal/gmail-mcp.git
cd gmail-mcp

  2. Configure um ambiente virtual usando uv:

    pip install uv
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

  3. Instale as dependências:

    uv pip install -e .

⚙️ Configuração

Passo 1: Autentique-se com o Google

  1. Acesse o Google Cloud Console
  2. Crie um novo projeto ou selecione um existente
  3. Habilite as APIs do Google:
  4. Configure a tela de consentimento OAuth:
    • Selecione o tipo de usuário "Externo"
    • Adicione seu e-mail como usuário de teste
    • Adicione todos os escopos do Gmail e do Calendar
  5. Crie credenciais OAuth 2.0:
    • Escolha "Aplicativo para desktop" como tipo de aplicativo
    • Baixe o arquivo JSON de credenciais e copie o Client ID e o Client Secret

Passo 2: Configure o Claude Desktop

  1. Crie ou edite o arquivo claude_desktop_config.json em /Users/<username>/Library/Application Support/Claude
  2. Adicione a seguinte configuração, substituindo os espaços reservados pelos seus valores reais:
{
  "mcpServers": {
    "gmail-mcp": {
      "command": "/<absolute-path>/gmail-mcp/.venv/bin/mcp",
      "args": [
        "run",
        "/<absolute-path>/gmail-mcp/gmail_mcp/main.py:mcp"
      ],
      "cwd": "/<absolute-path>/gmail-mcp",
      "env": {
        "PYTHONPATH": "/<absolute-path>/gmail-mcp",
        "CONFIG_FILE_PATH": "/<absolute-path>/gmail-mcp/config.yaml",
        "GOOGLE_CLIENT_ID": "<your-client-id>",
        "GOOGLE_CLIENT_SECRET": "<your-client-secret>",
        "TOKEN_ENCRYPTION_KEY": "<generate-a-random-key>"
      }
    }
  }
}

Observações:

  • Substitua <absolute-path> pelo caminho real para o diretório gmail-mcp
  • Substitua <your-client-id> e <your-client-secret> pelas suas credenciais OAuth do Google (geradas anteriormente no arquivo json)
  • Opcional: gere uma chave de criptografia aleatória com: python -c "import os; from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

A configuração foi projetada para manter dados sensíveis (client ID, client secret e chave de criptografia) no arquivo de configuração do Claude Desktop, enquanto as configurações não sensíveis são armazenadas no arquivo config.yaml incluído no repositório.

Passo 3: Use o Claude Desktop

  1. Abra o Claude Desktop
  2. Digite um prompt como: "Por favor, recupere meu último e-mail"
  3. O Claude deve conectar-se automaticamente ao servidor MCP e pedir que você autentique sua conta do Gmail (criando o arquivo tokens.json)

❓ Solução de Problemas

Nota Importante sobre MCP

Se o Claude Desktop não conectar automaticamente (ou seja, você não vê o ícone da ferramenta abaixo do campo de entrada do prompt), você pode tentar:

  • Reiniciar o Claude Desktop
  • Pedir ao Claude para "Usar o servidor MCP do Gmail"
  • Fazer login no Gmail manualmente usando um destes métodos:

Nota Importante sobre Autenticação

  1. Problemas de Autenticação:

    • Execute python debug/auth_test.py para testar o processo de autenticação com feedback detalhado
    • Verifique se o arquivo de token existe na raiz do projeto
    • Confirme que seu projeto no Google Cloud Console tem o URI de redirecionamento correto configurado
    • Certifique-se de que todos os escopos necessários foram adicionados à sua tela de consentimento OAuth
    • Se você vir erros "Scope has changed", garanta que o escopo openid está incluído na sua tela de consentimento OAuth
    • Se você vir erros "redirect_uri_mismatch", adicione o URI exato mostrado na mensagem de erro aos seus URIs de redirecionamento autorizados no Google Cloud Console
    • Se a página de retorno não carregar ou processar corretamente, verifique se a porta 8000 já está em uso por outro aplicativo

  2. Problemas com a API do Calendar:

    • Certifique-se de que você habilitou a API do Calendar no Google Cloud Console
    • Verifique se você concedeu todos os escopos necessários durante a autenticação
    • Execute python debug/reauth_calendar.py para reautenticar com os escopos da API do Calendar
    • Verifique se CALENDAR_API_ENABLED está definido como true nas suas variáveis de ambiente

Nota Importante sobre Integração com Calendário

A integração com calendário pode ser desativada no arquivo de configuração. Se você já autenticou anteriormente com o servidor MCP do Gmail e agora está habilitando a integração com calendário, será necessário reautenticar para conceder os escopos adicionais da API do Calendar. Você pode fazer isso:

  1. Excluindo o arquivo tokens.json existente (se presente, seja na raiz do projeto ou em ~/Users/<username/>gmail_mcp_tokens/tokens.json)
  2. Reiniciando o servidor MCP
  3. Seguindo o processo de autenticação novamente

👤 Uso

O Gmail MCP fornece ferramentas poderosas e sensíveis ao contexto para gerenciar seus e-mails e calendário:

Gerenciamento de E-mails

  • Visão Geral de E-mails: Tenha uma visão abrangente da sua caixa de entrada com contagens e e-mails recentes
  • Busca Avançada: Use a poderosa sintaxe de busca do Gmail para encontrar e-mails específicos
  • Análise Detalhada de E-mails: Veja e-mails com contexto completo, incluindo histórico de conversa e informações do remetente

Respostas de E-mail Sensíveis ao Contexto

  • Preparação Inteligente de Respostas: Analise o contexto completo de uma conversa de e-mail antes de responder
  • Análise de Padrões de Comunicação: Entenda seu histórico de comunicação com o remetente
  • Elaboração Personalizada: Crie respostas que correspondam ao seu estilo de comunicação com contatos específicos
  • Reconhecimento de Entidades: Identifique datas, horários, itens de ação e outras entidades importantes em e-mails
  • Contexto de E-mails Relacionados: Considere outros e-mails relevantes ao elaborar respostas

Integração com Calendário

  • Criação de Eventos: Crie eventos de calendário com descrições de horário em linguagem natural
  • Detecção de Eventos: Detecte automaticamente eventos potenciais mencionados em e-mails
  • Gerenciamento de Calendário: Veja, pesquise e gerencie seus próximos eventos de calendário
  • Agendamento Inteligente: Agende reuniões com contexto apropriado de conversas por e-mail

Exemplos de Solicitações

Você pode pedir ao Claude para usar essas capacidades com solicitações em linguagem natural como:

  • "Mostre-me uma visão geral da minha caixa de entrada"
  • "Encontre todos os e-mails não lidos do meu chefe sobre o relatório trimestral"
  • "Ajude-me a responder o último e-mail da Sarah sobre o prazo do projeto"
  • "Crie um evento de calendário para a reunião de equipe mencionada no e-mail do João"
  • "Quais reuniões tenho agendadas para a próxima semana?"
  • "Analise esta conversa de e-mail e ajude-me a entender os pontos principais antes de responder"
  • "Elabore uma resposta para este e-mail considerando minhas comunicações anteriores com esta pessoa"

Recursos Disponíveis

O MCP fornece recursos contextuais ricos que o Claude pode acessar:

  • Contexto de E-mail: Informações detalhadas sobre e-mails específicos
  • Contexto de Conversa: Histórico completo de conversas para conversas de e-mail
  • Contexto do Remetente: Informações sobre seu relacionamento e histórico de comunicação com remetentes
  • Status de Autenticação: Estado atual da autenticação com o Google
  • Status do Gmail: Visão geral da sua conta do Gmail
  • Informações do Servidor: Detalhes sobre a configuração do servidor MCP

Guias Disponíveis

O MCP inclui vários guias para ajudá-lo a aproveitar ao máximo suas capacidades:

  • Guia de Início Rápido: Instruções básicas para começar
  • Guia de Autenticação: Ajuda com o processo de autenticação
  • Guia de Busca: Referência da sintaxe avançada de busca do Gmail
  • Guia de Respostas: Melhores práticas para respostas de e-mail sensíveis ao contexto
  • Guia de Depuração: Solução de problemas comuns

☑️ Este MCP é configurado para que o Claude sempre peça sua confirmação antes de realizar qualquer ação importante, como enviar um e-mail ou criar uma reunião.

⚠ Aviso de Beta

Este MCP é um trabalho em andamento e está atualmente em beta.

📝 Licença

Este projeto é licenciado sob a Licença MIT.

💡 Agradecimentos

  • Este projeto usa o Model Context Protocol (MCP) desenvolvido pela Anthropic
  • O acesso à API do Gmail é fornecido pelos serviços de API do Google