Gmail MCP Server

Servidor MCP do Gmail

Um servidor MCP (Model Context Protocol) que fornece recursos de integração com o Gmail para clientes MCP como o Claude Desktop.

Recursos

• Visualizar e-mails recentes da sua caixa de entrada do Gmail
• Pesquisar e-mails usando a sintaxe de pesquisa do Gmail
• Autenticação OAuth2 segura com a API do Gmail

Configuração

1. Configuração do Projeto no Google Cloud

1. Crie um projeto no Google Cloud em https://console.cloud.google.com/
2. Ative a API do Gmail
3. Crie credenciais OAuth 2.0:
   • Tipo de aplicativo: Aplicativo de desktop
   • Baixe as credenciais como credentials.json

2. Instalação

# Create a conda environment
conda create -n mcp-gmail python=3.12
conda activate mcp-gmail

# Install the package
cd gmail-mcp-server
pip install -e .

3. Configuração para o Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "/path/to/conda/envs/mcp-gmail/bin/python",
      "args": ["-m", "gmail_mcp_server.server"],
      "env": {
        "PYTHONPATH": "/path/to/gmail-mcp-server/src",
        "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json",
        "GMAIL_TOKEN_FILE": "/path/to/token.json"
      }
    }
  }
}

Substitua /path/to/ pelos seus caminhos reais. O arquivo de token será criado automaticamente quando você autenticar pela primeira vez.

4. Primeira Execução

Quando você tentar acessar o Gmail pelo Claude pela primeira vez, será solicitado a autorizar o aplicativo no seu navegador. Após a autorização, suas credenciais serão salvas no arquivo de token para uso futuro.

Recursos Disponíveis

• gmail://inbox/recent - Retorna seus 10 e-mails mais recentes

Ferramentas Disponíveis

• search_emails
  • Descrição: Pesquisa e-mails do Gmail com uma consulta
  • Parâmetros:
    • query (obrigatório): Consulta de pesquisa do Gmail (usa a sintaxe de pesquisa padrão do Gmail)
    • max_results (opcional): Número máximo de resultados a retornar (padrão: 10)

Exemplo de pesquisa:

Could you show me any emails from sanrio in the last two days?

Segurança

Este servidor requer autenticação OAuth2 com o Gmail:

• Você será solicitado a autorizar o acesso no seu navegador no primeiro uso
• As credenciais são armazenadas localmente no arquivo de token especificado
• O acesso pode ser revogado a qualquer momento nas configurações da sua Conta do Google
• Apenas acesso de leitura ao Gmail é solicitado (sem permissões de escrita)

Variáveis de Ambiente

• GMAIL_CREDENTIALS_FILE (obrigatório): Caminho para o seu arquivo de credenciais OAuth do Google
• GMAIL_TOKEN_FILE (obrigatório): Caminho onde o token de autenticação será salvo

Para testes, você pode executar o servidor diretamente:

GMAIL_CREDENTIALS_FILE="/path/to/credentials.json" \
GMAIL_TOKEN_FILE="/path/to/token.json" \
python -m gmail_mcp_server.server

Desenvolvimento

O servidor usa o Model Context Protocol para fornecer:

• Acesso a recursos para e-mails recentes
• Suporte a ferramentas para pesquisa de e-mails
• Fluxo de autenticação OAuth2 seguro
• Atualização automática de token

Registro de Logs

O servidor registra informações detalhadas sobre suas operações no stderr, incluindo:

• Informações de inicialização do servidor
• Status de autenticação
• Uso de recursos e ferramentas
• Quaisquer erros ou problemas

Contribuindo

Pull requests são bem-vindos! Por favor, certifique-se de:

• Atualizar a documentação para quaisquer novos recursos
• Adicionar tratamento de erros adequado
• Testar o fluxo OAuth com novos recursos
• Seguir o estilo de código existente