Servidor MCP Gmail | Awesome MCP Servers

Servidor MCP Aprimorado para Gmail

Um servidor de Model Context Protocol (MCP) poderoso e repleto de recursos para integração com o Gmail, escrito em Python. Este servidor permite que assistentes de IA como o Claude interajam com o Gmail por meio de linguagem natural, fornecendo recursos abrangentes de gerenciamento de e-mail.

🌟 Principais Recursos

📧 Gerenciamento Completo de E-mail

Enviar e-mails com assunto, conteúdo e destinatários personalizáveis
Ler e recuperar conteúdo de e-mails com metadados completos
Mover e-mails para a lixeira com confirmação
Marcar e-mails como lidos/não lidos
Abrir e-mails diretamente no navegador

📝 Gerenciamento de Rascunhos

Criar rascunhos de e-mail para revisão posterior
Listar todos os rascunhos de e-mail
Editar rascunhos existentes

🏷️ Gerenciamento Avançado de Rótulos

Listar todos os rótulos disponíveis
Criar rótulos personalizados
Aplicar/remover rótulos de e-mails
Renomear rótulos existentes
Excluir rótulos não utilizados
Pesquisar e-mails por rótulo

📁 Organização de Pastas

Criar novas pastas (implementadas como rótulos do Gmail)
Mover e-mails entre pastas
Listar todas as pastas disponíveis

🔍 Pesquisa e Filtragem Poderosas

Pesquisar e-mails usando a sintaxe avançada de consulta do Gmail
Criar, gerenciar e excluir filtros de e-mail
Filtrar por remetente, destinatário, assunto, conteúdo e mais
Personalizar resultados de pesquisa com parâmetros flexíveis

🗄️ Gerenciamento de Arquivo

Arquivar e-mails (remover da caixa de entrada sem excluir)
Arquivar em lote vários e-mails que correspondam aos critérios de pesquisa
Listar todos os e-mails arquivados
Restaurar e-mails arquivados para a caixa de entrada

🚀 Primeiros Passos

Pré-requisitos

Python 3.8+
Projeto do Google Cloud com a API do Gmail habilitada
Credenciais OAuth 2.0

Instalação

# Clone the repository
git clone https://github.com/theposch/gmail-mcp.git
cd gmail-mcp

# Set up a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package
pip install -e .

Configuração do Google Cloud

Crie um novo projeto do Google Cloud
Habilite a API do Gmail
Configure a tela de consentimento OAuth:
- Selecione o tipo de usuário "Externo"
- Adicione seu e-mail como usuário de teste
- Adicione o escopo: https://www.googleapis.com/auth/gmail/modify
Crie credenciais OAuth 2.0:
- Escolha "Aplicativo de desktop" como tipo de aplicativo
- Baixe o arquivo JSON de credenciais

Configuração

Armazene suas credenciais com segurança e especifique sua localização ao executar o servidor:

# Example directory structure for credentials
mkdir -p ~/.gmail-mcp
# Move your downloaded credentials file
mv ~/Downloads/client_secret_*.json ~/.gmail-mcp/credentials.json

🔧 Uso

Executando com o Claude Desktop

Adicione o seguinte ao arquivo de configuração do Claude Desktop (normalmente em ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "gmail": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/gmail-mcp",
        "run",
        "gmail",
        "--creds-file-path",
        "/absolute/path/to/credentials.json",
        "--token-path",
        "/absolute/path/to/tokens.json"
      ]
    }
  }
}

Testando com o MCP Inspector

Para testes e depuração, use o MCP Inspector:

npx @modelcontextprotocol/inspector uv run /path/to/gmail-mcp/src/gmail/server.py --creds-file-path /path/to/credentials.json --token-path /path/to/tokens.json

🔐 Considerações de Segurança

Nunca envie credenciais ou arquivos de token para o controle de versão
Armazene credenciais em um local seguro com permissões apropriadas
O servidor solicitará confirmação do usuário antes de executar ações sensíveis
Revise o Google Cloud Console regularmente para atividades incomuns
Considere usar variáveis de ambiente para caminhos sensíveis

🛠️ Arquitetura

Esta implementação apresenta uma arquitetura abrangente de arquivo único que lida com todas as operações do Gmail por meio das bibliotecas de cliente da API do Google. Os principais componentes incluem:

Autenticação OAuth2 com renovação automática de token
Tratamento abrangente de erros e registro de logs
Definições de ferramentas estruturadas com esquemas de entrada claros
Análise e formatação eficientes de e-mail

📚 Exemplos de Prompts

Experimente estes prompts com o Claude após conectar o servidor MCP do Gmail:

"Mostre-me meus e-mails não lidos"
"Pesquise e-mails de example@domain.com com anexos"
"Crie um novo rótulo chamado 'Projetos Importantes'"
"Redija um e-mail para john@example.com sobre a próxima reunião"
"Arquive todos os e-mails de newsletter@example.com"
"Crie um filtro para rotular automaticamente e-mails da minha equipe"

🤝 Contribuindo

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

Faça um fork do repositório
Crie sua branch de recurso (git checkout -b feature/amazing-feature)
Faça commit das suas alterações (git commit -m 'Add some amazing feature')
Envie para a branch (git push origin feature/amazing-feature)
Abra um Pull Request

📄 Licença

Este projeto é licenciado sob a Licença GPL-3.0 - consulte o arquivo LICENSE para obter detalhes.

🙏 Agradecimentos

Inspirado por várias implementações de servidor MCP na comunidade
Construído com o framework Model Context Protocol
Usa as bibliotecas oficiais de cliente da API do Google

Gmail

Documentação