Servidor MCP Gmail | Awesome MCP Servers

Gmail MCP - Instalação Automática e Segura

Acesso de assistentes de IA ao Gmail por meio do Model Context Protocol (MCP)

Requisito essencial: Você deve ter o Claude Desktop instalado para poder utilizar este servidor MCP.

🧪 O que é MCP?

MCP (Model Context Protocol) é um protocolo de integração desenvolvido pela Anthropic para facilitar a comunicação entre modelos de linguagem (como ChatGPT ou Claude) e ferramentas externas (APIs, bancos de dados, serviços web, etc.). Seu objetivo é fornecer um contexto ampliado, estruturado e em tempo real aos modelos, permitindo que eles executem ações além do texto.

🎥 Vídeo com exemplo de uso

https://github.com/user-attachments/assets/e49b2d76-bcef-4d44-9222-6818f0f57998

🚀 Instalação rápida (Windows)

Primeiro:
- Acesse o Google Cloud Console
- Crie um projeto e habilite a API do Gmail
- Adicione http://localhost:8080/ às URIs de redirecionamento autorizadas
- Baixe o arquivo client_secret_...json e deixe-o na sua pasta Downloads (não se preocupe com o nome nem com a localização final)
- O instalador detectará e moverá o arquivo automaticamente para a pasta correta e com o nome adequado

[!IMPORTANT] Você só precisa baixar o arquivo de credenciais do Google Cloud depois de configurar as URIs de redirecionamento autorizadas e deixá-lo em Downloads. Não se preocupe com o nome nem com a localização final, o instalador cuida de tudo!

Clone este repositório a partir do seu terminal:

git clone https://github.com/FranciscoYuster/claude-client-gmail-mcp
cd claude-client-gmail-mcp

E execute o script:
```
python setup.py
```
O instalador fará o resto
Quando você vir a mensagem final, abra o Claude Desktop e aproveite!

💻 Instalação no macOS / Linux

Siga os mesmos passos do Google Cloud indicados acima para obter seu arquivo de credenciais e deixá-lo em Downloads.

Clone este repositório a partir do seu terminal:

git clone https://github.com/FranciscoYuster/gmail-client-mcp-server
cd gmail-client-mcp-server

Execute o script para sistemas Unix:
```
python3 setupUnix.py
```
O instalador fará o resto.
Quando você vir a mensagem final, abra o Claude Desktop e aproveite!

[!IMPORTANT] Se você usa Windows, execute: python setup.py Se você usa macOS ou Linux, execute: python3 setupUnix.py Ambos os scripts executam a instalação, mas cada um está adaptado ao seu sistema operacional.

🔒 Segurança

[!WARNING] Nunca envie nem compartilhe seu arquivo de credenciais. Se você o expor por engano, exclua-o e gere um novo no Google Cloud Console. O script nunca envia nem distribui seus dados sensíveis.

📝 Pré-requisitos

Python 3.11 ou superior
git
Conta do Gmail
Claude Desktop

[!TIP] O instalador irá guiá-lo para instalar qualquer requisito que estiver faltando.

⚙️ Configuração manual

🚀 Configuração

Clone este repositório:

git clone https://github.com/FranciscoYuster/claude-client-gmail-mcp
cd claude-client-gmail-mcp

Crie e ative um ambiente virtual:

uv init
# o alternativamente
uv venv

Em seguida, ative-o:

.venv\scripts\activate

Instale as dependências:
```
uv pip install -r requirements.txt
```
Configure as credenciais OAuth:
- Crie um diretório chamado credentials na raiz do projeto
- Crie um projeto no Google Cloud Console
- Habilite a API do Gmail
- Crie credenciais OAuth
- Adicione a seguinte URI às URIs de redirecionamento autorizadas:
```
http://localhost:8080/
```
- Baixe o arquivo JSON de credenciais e salve-o como credentials/client_secret_gmail_oauth.json

[!CAUTION] Certifique-se de que o caminho e o nome do arquivo de credenciais estejam corretos para evitar erros de autenticação.

Adicione o servidor MCP à sua configuração JSON. Consulte a documentação oficial do seu cliente MCP para instruções específicas. Certifique-se de ajustar o caminho conforme o seu ambiente:

{
    "mcpServers": {
        "gmail-mcp": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/your/gmail-mcp/src",
                "run",
                "main.py"
            ]
        }
    }
}

Execute o Claude Desktop

Ferramentas disponíveis

O servidor inclui uma série de ferramentas para operar e automatizar o Gmail a partir de assistentes de IA. Essas ferramentas permitem enviar, ler, buscar, gerenciar e-mails e etiquetas. A seguir, estão listadas as principais funções disponíveis:

Operações de e-mail

Enviar e-mails (com anexos, CC, BCC, resposta a threads)
Criar rascunhos de e-mails (com anexos)
Baixar anexos de uma mensagem
Ler e-mails por ID (texto e HTML, com fragmentação para mensagens grandes)
Buscar e-mails com filtros avançados (consulta, etiquetas, remetente, anexos, paginação)
Obter threads completos de conversa
Marcar como lido/não lido/importante/não importante

Gerenciamento de etiquetas

Adicionar ou remover etiquetas de um e-mail
Criar novas etiquetas
Excluir etiquetas por nome
Listar todas as etiquetas
Obter ou criar etiquetas por nome
Atualizar configurações de etiquetas (nome, visibilidade, cor)
Buscar etiquetas por nome

Essas ferramentas permitem um gerenciamento avançado e automatizado do e-mail e das etiquetas do Gmail, facilitando a integração com assistentes de IA e fluxos de trabalho

📝 Licença

MIT. Consulte o arquivo LICENSE.

Gmail MCP

Documentação