Gmail Guardian

Agente inteligente para gerenciamento do Gmail, construído com Claude (Anthropic SDK) e integrado via MCP server.

Funcionalidades

Skill	Descrição
triagem-email	Classifica emails não lidos por categoria e prioridade
classificar-newsletters	Identifica e organiza newsletters por tema
limpar-promocoes	Arquiva emails promocionais em massa com salvaguardas
resumir-importantes	Gera briefings com pontos de ação e prazos
sugerir-filtros	Analisa padrões e cria filtros automáticos
responder-rascunho	Gera rascunhos de resposta para emails pendentes
auditoria-acoes	Log completo de ações com suporte a reversão

Pré-requisitos

• Python 3.11+
• Conta Google com Gmail
• Chave de API da Anthropic
• Credenciais OAuth2 do Google Cloud Console

Instalação

# 1. Instalar dependências
pip install -r requirements.txt

# 2. Configurar variáveis de ambiente
cp .env.example .env
# Editar .env com suas chaves

# 3. Baixar credentials.json do Google Cloud Console
# (APIs & Services > Credentials > OAuth 2.0 Client IDs)
# Salvar em config/credentials.json

Uso

Modo interativo (REPL)

python run.py

Gmail Guardian — Agente de gerenciamento de emails
Digite 'sair' para encerrar | 'log' para ver auditoria

Você: triar meus emails não lidos
Agente: Buscando emails não lidos...

Como MCP Server (Claude Code)

python run.py --mcp

Adicione ao seu ~/.claude/settings.json:

{
  "mcpServers": {
    "gmail": {
      "command": "python",
      "args": ["/caminho/para/email-guardian/run.py", "--mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "GOOGLE_CREDENTIALS_PATH": "/caminho/para/credentials.json"
      }
    }
  }
}

Depois use no Claude Code:

/triagem-email
/limpar-promocoes
/resumir-importantes

Estrutura do Projeto

email-guardian/
├── .claude/              # Configuração do agente e skills para Claude Code
│   ├── agents/           # Definição do agente gmail-guardian
│   └── skills/           # Skills invocáveis via /skill-name
├── agent/                # Orquestração do agente (Anthropic SDK)
├── gmail_mcp/            # MCP Server + ferramentas Gmail
│   ├── services/         # Wrappers da Gmail API
│   ├── tools/            # Implementação das ferramentas MCP
│   └── schemas/          # Dataclasses para tipagem
├── config/               # Settings, políticas e categorias
├── tests/                # Testes unitários
├── .env.example          # Template de variáveis de ambiente
├── requirements.txt
└── run.py                # Entry point

Segurança

• Nunca deleta emails permanentemente sem confirmação explícita
• Preserva automaticamente confirmações de pedido e notas fiscais
• Todas as ações são registradas no log de auditoria
• Suporte a DRY_RUN=true para simular sem modificar

Testes

pytest tests/ -v