Gmail MCP Server

Um servidor MCP que se integra com a API do Gmail para gerenciamento inteligente de e-mails, incluindo busca, categorização e arquivamento.

GitHub
2
Experimente este MCPPatrocinado

Documentação

Servidor MCP do Gmail

Node.js Version License: MIT MCP Protocol TypeScript

Um servidor abrangente do Model Context Protocol (MCP) que se integra à API do Gmail para fornecer recursos inteligentes de gerenciamento de e-mail. Inclui categorização avançada de e-mails, busca, arquivamento, exclusão e limpeza automatizada com mais de 25 ferramentas MCP para gerenciamento completo do ciclo de vida de e-mails.

🚀 Principais Recursos

📧 Gerenciamento Inteligente de E-mails

  • Categorização com IA: Categorize e-mails automaticamente por importância (alta/média/baixa) usando análise avançada
  • Busca e Filtragem Inteligentes: Busca avançada com múltiplos critérios, buscas salvas e combinações de filtros
  • Processamento em Tempo Real: Processamento de tarefas em segundo plano para operações de longa duração com acompanhamento de progresso

🗄️ Sistema de Arquivamento e Exportação

  • Arquivamento Inteligente: Arquive e-mails com base em regras com múltiplos formatos de exportação (MBOX, JSON, CSV)
  • Mecanismo de Regras Automatizadas: Crie e gerencie regras automáticas de arquivamento com agendamento
  • Capacidade de Restauração: Restaure e-mails arquivados anteriormente com metadados completos

🧹 Automação Avançada de Limpeza

  • Limpeza Baseada em Políticas: Mais de 13 ferramentas de limpeza com políticas configuráveis para gerenciamento automatizado de e-mails
  • Rastreamento de Padrões de Acesso: Rastreie padrões de acesso a e-mails para decisões inteligentes de limpeza
  • Design com Segurança em Primeiro Lugar: Opções de simulação, etapas de confirmação e capacidades de reversão

📊 Análises e Monitoramento

  • Estatísticas Abrangentes: Análises detalhadas de uso de e-mails por categoria, ano, tamanho e mais
  • Monitoramento de Saúde do Sistema: Métricas em tempo real, acompanhamento de desempenho e relatórios de saúde do sistema
  • Recomendações de Limpeza: Recomendações orientadas por IA para gerenciamento ideal de e-mails

🔒 Segurança e Proteção

  • Autenticação OAuth2: Integração segura com a API do Gmail com armazenamento criptografado de tokens
  • Segurança em Múltiplas Camadas: Solicitações de confirmação, modos de simulação e limites máximos de exclusão
  • Registro de Auditoria: Registro completo de operações e rastreamento de erros

📋 Sumário

🚀 Início Rápido

Pré-requisitos

  • Node.js 18+ e npm
  • Conta no Google Cloud Platform com a API do Gmail ativada
  • Credenciais OAuth2 (ID do Cliente e Segredo do Cliente)

Configuração Automatizada

# Clone and install
git clone <repository-url>
cd gmail-mcp-server
npm run setup  # Interactive setup wizard
npm install && npm run build

Primeira Execução

# Start the MCP server
npm start

# Authenticate with Gmail (run in your MCP client)
{
  "tool": "authenticate"
}

📦 Instalação

Método 1: Configuração Rápida (Recomendado)

# 1. Clone repository
git clone <repository-url>
cd gmail-mcp-server

# 2. Run interactive setup
npm run setup

# 3. Install and build
npm install
npm run build

O script de configuração irá guiá-lo por:

  • 🔑 Configuração das credenciais do Google Cloud
  • 📁 Criação dos diretórios necessários
  • ⚙️ Configuração das variáveis de ambiente
  • 🔧 Configuração inicial

Método 2: Configuração Manual

  1. Configure as credenciais do Google Cloud:

    • Acesse o Console do Google Cloud
    • Crie um projeto ou selecione um existente
    • Ative a API do Gmail
    • Crie credenciais OAuth2 (aplicativo de desktop)
    • Baixe o credentials.json para a raiz do projeto

  2. Configure o ambiente:

    cp .env.example .env
# Edit .env with your settings

  3. Crie os diretórios:

    mkdir -p data logs archives

  4. Instale e compile:

    npm install
npm run build

🔧 Configuração

Configuração do Cliente MCP

Para o Claude Desktop:

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/path/to/gmail-mcp-server/build/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Para outros clientes MCP:

# Direct stdio connection
node /path/to/gmail-mcp-server/build/index.js

Configuração de Ambiente

Principais variáveis de ambiente no .env:

GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REDIRECT_URI=http://localhost:3000/oauth2callback
STORAGE_PATH=./data
CACHE_TTL=3600
LOG_LEVEL=info

🛠️ Referência de Ferramentas MCP

O Servidor MCP do Gmail fornece mais de 25 ferramentas especializadas organizadas em categorias lógicas para gerenciamento abrangente de e-mails. Cada ferramenta inclui recursos de segurança, validação de parâmetros e tratamento detalhado de erros.

🔐 Ferramentas de Autenticação

authenticate

Inicia o fluxo de autenticação OAuth2 com a API do Gmail.

Parâmetros:

  • scopes (array, opcional): Escopos OAuth adicionais além de leitura/gravação do Gmail

Retorna: Status da autenticação e e-mail do usuário

{
  "tool": "authenticate",
  "arguments": {
    "scopes": ["https://www.googleapis.com/auth/gmail.modify"]
  }
}

📧 Ferramentas de Gerenciamento de E-mails

list_emails

Lista e-mails com filtragem abrangente e paginação.

Parâmetros:

  • category (string): Filtra por nível de importância (high|medium|low)
  • year (número): Filtra por ano específico
  • size_min (número): Tamanho mínimo em bytes
  • size_max (número): Tamanho máximo em bytes
  • archived (booleano): Inclui e-mails arquivados
  • has_attachments (booleano): Filtra pela presença de anexos
  • labels (array): Filtra por rótulos do Gmail
  • query (string): String de consulta personalizada do Gmail
  • limit (número, padrão: 50): Resultados máximos
  • offset (número, padrão: 0): Pula os primeiros N resultados
{
  "tool": "list_emails",
  "arguments": {
    "category": "high",
    "year": 2024,
    "has_attachments": true,
    "limit": 25
  }
}

get_email_details

Recupera o conteúdo completo do e-mail e metadados.

Parâmetros:

  • id (string, obrigatório): ID da mensagem do Gmail

Retorna: Objeto de e-mail completo com cabeçalhos, corpo e anexos

{
  "tool": "get_email_details",
  "arguments": {
    "id": "18c2e4f5d9a8b7c3"
  }
}

categorize_emails

Analisa e categoriza e-mails por importância usando algoritmos de IA.

Parâmetros:

  • year (número, obrigatório): Ano para categorizar
  • force_refresh (booleano): Reanalisar e-mails já categorizados

Retorna: Status da tarefa de categorização e estatísticas

{
  "tool": "categorize_emails",
  "arguments": {
    "year": 2024,
    "force_refresh": true
  }
}

🔍 Ferramentas de Busca e Filtro

search_emails

Busca avançada de e-mails com múltiplos critérios e filtragem inteligente.

Parâmetros:

  • query (string): Consulta de busca por texto
  • category (string): Filtro de importância (high|medium|low)
  • year_range (objeto): Intervalo de datas com ano de start e/ou end
  • size_range (objeto): Intervalo de tamanho com min e/ou max bytes
  • sender (string): Filtra por endereço de e-mail do remetente
  • has_attachments (booleano): Filtro de presença de anexos
  • archived (booleano): Inclui e-mails arquivados
  • limit (número, padrão: 50): Resultados máximos
{
  "tool": "search_emails",
  "arguments": {
    "query": "project deadline",
    "category": "high",
    "year_range": { "start": 2024 },
    "size_range": { "min": 1048576 },
    "sender": "manager@company.com"
  }
}

save_search

Salva critérios de busca para reutilização rápida.

Parâmetros:

  • name (string, obrigatório): Nome para a busca salva
  • criteria (objeto, obrigatório): Critérios de busca a serem salvos
{
  "tool": "save_search",
  "arguments": {
    "name": "Large Recent Emails",
    "criteria": {
      "size_range": { "min": 5242880 },
      "year_range": { "start": 2024 }
    }
  }
}

list_saved_searches

Recupera todas as consultas de busca salvas.

Parâmetros: Nenhum

Retorna: Array de buscas salvas com estatísticas de uso

{
  "tool": "list_saved_searches"
}

📁 Ferramentas de Arquivamento e Exportação

archive_emails

Arquiva e-mails usando múltiplos métodos e formatos.

Parâmetros:

  • search_criteria (objeto): Critérios de seleção de e-mails
  • category (string): Arquiva por nível de importância
  • year (número): Arquiva e-mails de ano específico
  • older_than_days (número): Arquiva e-mails mais antigos que N dias
  • method (string, obrigatório): Método de arquivamento (gmail|export)
  • export_format (string): Formato ao exportar (mbox|json)
  • export_path (string): Destino de exportação personalizado
  • dry_run (booleano, padrão: falso): Modo de visualização
{
  "tool": "archive_emails",
  "arguments": {
    "category": "low",
    "older_than_days": 180,
    "method": "export",
    "export_format": "mbox",
    "dry_run": false
  }
}

restore_emails

Restaura e-mails de arquivos anteriores.

Parâmetros:

  • archive_id (string): Arquivo específico para restaurar
  • email_ids (array): IDs de e-mails individuais para restaurar
  • restore_labels (array): Rótulos a serem aplicados aos e-mails restaurados
{
  "tool": "restore_emails",
  "arguments": {
    "archive_id": "archive_2023_low_priority",
    "restore_labels": ["restored", "reviewed"]
  }
}

create_archive_rule

Cria regras automáticas de arquivamento com agendamento.

Parâmetros:

  • name (string, obrigatório): Nome descritivo da regra
  • criteria (objeto, obrigatório): Condições de arquivamento
  • action (objeto, obrigatório): Método e formato de arquivamento
  • schedule (string): Frequência de execução (daily|weekly|monthly)
{
  "tool": "create_archive_rule",
  "arguments": {
    "name": "Auto-archive old promotional emails",
    "criteria": {
      "category": "low",
      "older_than_days": 90,
      "labels": ["promotions"]
    },
    "action": {
      "method": "gmail"
    },
    "schedule": "weekly"
  }
}

list_archive_rules

Visualiza todas as regras de arquivamento configuradas e seu status.

Parâmetros:

  • active_only (booleano, padrão: falso): Mostrar apenas regras ativadas
{
  "tool": "list_archive_rules",
  "arguments": {
    "active_only": true
  }
}

export_emails

Exporta e-mails para formatos externos com suporte a upload em nuvem.

Parâmetros:

  • search_criteria (objeto): Filtros de seleção de e-mails
  • format (string, obrigatório): Formato de exportação (mbox|json|csv)
  • include_attachments (booleano, padrão: falso): Incluir anexos
  • output_path (string): Caminho de saída local
  • cloud_upload (objeto): Configuração de armazenamento em nuvem
{
  "tool": "export_emails",
  "arguments": {
    "format": "json",
    "search_criteria": { "year": 2023 },
    "include_attachments": true,
    "cloud_upload": {
      "provider": "gdrive",
      "path": "/backups/gmail-2023"
    }
  }
}

🗑️ Ferramentas de Exclusão e Limpeza

delete_emails

Exclui e-mails com segurança e verificações abrangentes de segurança.

⚠️ Nota de Segurança: Sempre use dry_run: true primeiro para visualizar as exclusões

Parâmetros:

  • search_criteria (objeto): Filtros de seleção de e-mails
  • category (string): Excluir por nível de importância
  • year (número): Excluir de ano específico
  • size_threshold (número): Excluir e-mails maiores que N bytes
  • skip_archived (booleano, padrão: verdadeiro): Pular e-mails arquivados
  • dry_run (booleano, padrão: falso): Modo de visualização
  • max_count (número, padrão: 10): Limite de segurança
{
  "tool": "delete_emails",
  "arguments": {
    "category": "low",
    "year": 2022,
    "dry_run": true,
    "max_count": 50
  }
}

empty_trash

Exclui permanentemente todos os e-mails na pasta de lixeira do Gmail.

⚠️ Operação Destrutiva: Isso exclui permanentemente os e-mails

Parâmetros:

  • dry_run (booleano, padrão: falso): Modo de visualização
  • max_count (número, padrão: 10): Limite de segurança
{
  "tool": "empty_trash",
  "arguments": {
    "dry_run": true,
    "max_count": 100
  }
}

trigger_cleanup

Executa limpeza manual usando políticas específicas.

Parâmetros:

  • policy_id (string, obrigatório): Política de limpeza a ser executada
  • dry_run (booleano, padrão: falso): Modo de visualização
  • max_emails (número): Limite de processamento
  • force (booleano, padrão: falso): Executar mesmo se a política estiver desativada
{
  "tool": "trigger_cleanup",
  "arguments": {
    "policy_id": "old_low_priority_emails",
    "dry_run": true,
    "max_emails": 500
  }
}

get_cleanup_status

Monitora o status do sistema de automação de limpeza.

Parâmetros: Nenhum

Retorna: Status do sistema, tarefas ativas e métricas de saúde

{
  "tool": "get_cleanup_status"
}

get_system_health

Obtém métricas abrangentes de saúde e desempenho do sistema.

Parâmetros: Nenhum

Retorna: Métricas de desempenho, uso de armazenamento e status do sistema

{
  "tool": "get_system_health"
}

create_cleanup_policy

Cria políticas avançadas de limpeza com critérios detalhados.

Parâmetros:

  • name (string, obrigatório): Nome da política
  • enabled (booleano, padrão: verdadeiro): Status da política
  • priority (número, padrão: 50): Prioridade de execução (0-100)
  • criteria (objeto, obrigatório): Condições de limpeza
  • action (objeto, obrigatório): Ação a ser tomada
  • safety (objeto, obrigatório): Configuração de segurança
  • schedule (objeto): Agendamento opcional
{
  "tool": "create_cleanup_policy",
  "arguments": {
    "name": "Aggressive Low Priority Cleanup",
    "priority": 80,
    "criteria": {
      "age_days_min": 90,
      "importance_level_max": "low",
      "spam_score_min": 0.7
    },
    "action": {
      "type": "delete"
    },
    "safety": {
      "max_emails_per_run": 100,
      "require_confirmation": false,
      "dry_run_first": true
    }
  }
}

update_cleanup_policy

Modifica a configuração de uma política de limpeza existente.

Parâmetros:

  • policy_id (string, obrigatório): Política a ser atualizada
  • updates (objeto, obrigatório): Alterações a serem aplicadas
{
  "tool": "update_cleanup_policy",
  "arguments": {
    "policy_id": "policy_123",
    "updates": {
      "enabled": false,
      "safety": { "max_emails_per_run": 50 }
    }
  }
}

list_cleanup_policies

Visualiza todas as políticas de limpeza e suas configurações.

Parâmetros:

  • active_only (booleano, padrão: falso): Mostrar apenas políticas ativadas
{
  "tool": "list_cleanup_policies",
  "arguments": {
    "active_only": true
  }
}

delete_cleanup_policy

Remove uma política de limpeza permanentemente.

Parâmetros:

  • policy_id (string, obrigatório): Política a ser excluída
{
  "tool": "delete_cleanup_policy",
  "arguments": {
    "policy_id": "outdated_policy_456"
  }
}

create_cleanup_schedule

Agenda execução automática de políticas de limpeza. Parâmetros:

  • name (string, obrigatório): Nome do agendamento
  • type (string, obrigatório): Tipo de agendamento (daily|weekly|monthly|interval|cron)
  • expression (string, obrigatório): Expressão do agendamento
  • policy_id (string, obrigatório): Política a ser agendada
  • enabled (boolean, padrão: true): Status do agendamento
{
  "tool": "create_cleanup_schedule",
  "arguments": {
    "name": "Nightly Low Priority Cleanup",
    "type": "daily",
    "expression": "02:00",
    "policy_id": "low_priority_policy",
    "enabled": true
  }
}

update_cleanup_automation_config

Atualiza as configurações globais de automação de limpeza.

Parâmetros:

  • config (objeto, obrigatório): Atualizações de configuração
{
  "tool": "update_cleanup_automation_config",
  "arguments": {
    "config": {
      "continuous_cleanup": {
        "enabled": true,
        "target_emails_per_minute": 10
      }
    }
  }
}

get_cleanup_metrics

Recupera análises do sistema de limpeza e dados de desempenho.

Parâmetros:

  • hours (número, padrão: 24): Janela de histórico em horas
{
  "tool": "get_cleanup_metrics",
  "arguments": {
    "hours": 168
  }
}

get_cleanup_recommendations

Obtenha recomendações de políticas de limpeza com IA.

Parâmetros: Nenhum

Retorna: Políticas recomendadas com base na análise de e-mails

{
  "tool": "get_cleanup_recommendations"
}

📊 Ferramentas de Estatísticas e Análises

get_email_stats

Estatísticas e análises abrangentes de uso de e-mail.

Parâmetros:

  • group_by (string): Método de agrupamento (year|category|label|all)
  • year (número): Filtrar por ano específico

Retorna: Estatísticas detalhadas por categorias, anos, tamanhos e armazenamento

{
  "tool": "get_email_stats",
  "arguments": {
    "group_by": "all"
  }
}

⚙️ Ferramentas de Gerenciamento de Tarefas

list_jobs

Visualize todas as tarefas em segundo plano com opções de filtro.

Parâmetros:

  • limit (número, padrão: 50): Resultados máximos
  • offset (número, padrão: 0): Pular as primeiras N tarefas
  • status (string): Filtrar por status (pending|running|completed|failed)
  • job_type (string): Filtrar por tipo de tarefa
{
  "tool": "list_jobs",
  "arguments": {
    "status": "running",
    "limit": 25
  }
}

get_job_status

Obtenha o status detalhado de uma tarefa específica em segundo plano.

Parâmetros:

  • id (string, obrigatório): ID da tarefa a ser consultada

Retorna: Detalhes da tarefa, progresso e resultados

{
  "tool": "get_job_status",
  "arguments": {
    "id": "categorization_job_789"
  }
}

cancel_job

Cancela uma tarefa em segundo plano em execução.

Parâmetros:

  • id (string, obrigatório): ID da tarefa a ser cancelada
{
  "tool": "cancel_job",
  "arguments": {
    "id": "cleanup_job_101112"
  }
}

Exemplos de Fluxos de Trabalho

Configuração Inicial

// 1. Authenticate
{
  "tool": "authenticate"
}

// 2. Categorize all emails
{
  "tool": "categorize_emails",
  "arguments": {
    "force_refresh": true
  }
}

// 3. View statistics
{
  "tool": "get_email_stats",
  "arguments": {
    "group_by": "all"
  }
}

Limpar E-mails Antigos

// 1. Search for old large emails
{
  "tool": "search_emails",
  "arguments": {
    "year_range": { "end": 2022 },
    "size_range": { "min": 5242880 }
  }
}

// 2. Archive them
{
  "tool": "archive_emails",
  "arguments": {
    "year": 2022,
    "size_threshold": 5242880,
    "method": "export",
    "export_format": "mbox"
  }
}

Configuração de Limpeza Automatizada

// 1. Start cleanup automation [TODO]
{
  "tool": "start_cleanup_automation",
  "arguments": {
    "policies": ["old_emails", "large_attachments"],
    "schedule": "daily"
  }
}

// 2. Monitor cleanup status
{
  "tool": "get_cleanup_status"
}

Desenvolvimento

Estrutura do Projeto

gmail-mcp-server/
├── src/
│   ├── auth/           # Authentication management
│   ├── cache/          # Caching layer
│   ├── categorization/ # Email categorization engine
│   ├── cleanup/        # Cleanup automation
│   ├── database/       # SQLite database management
│   ├── delete/         # Email deletion logic
│   ├── email/          # Email fetching and processing
│   ├── search/         # Search functionality
│   ├── archive/        # Archive management
│   ├── tools/          # MCP tool definitions
│   ├── types/          # TypeScript type definitions
│   └── utils/          # Utility functions
├── build/              # Compiled JavaScript
├── data/               # Local storage
├── logs/               # Application logs
└── archives/           # Email archives

Executando em Desenvolvimento

npm run watch  # Watch mode for TypeScript
npm run dev    # Run with tsx (hot reload)

Testando com o MCP Inspector

npm run inspector

Testes

O projeto inclui suítes de testes abrangentes para garantir a confiabilidade e a correção de todos os recursos.

Executando Testes

# Run all tests
npm test

# Run with coverage
npm test -- --coverage

# Run specific test suite
npm test -- --testPathPattern=delete

Testes de Integração

Testes de Exclusão de E-mail

A funcionalidade de exclusão possui testes de integração extensivos cobrindo todos os cenários:

# Run delete integration tests with the dedicated runner
node scripts/test-delete-integration.js

# With coverage report
node scripts/test-delete-integration.js --coverage

# Run specific test scenarios
node scripts/test-delete-integration.js --filter "delete by category"

Para informações detalhadas sobre testes de exclusão de e-mail, consulte Documentação de Testes de Exclusão de E-mail.

Estrutura de Testes

tests/
├── unit/               # Unit tests for individual components
├── integration/        # Integration tests for complete features
│   └── delete/        # Delete email integration tests
├── fixtures/          # Shared test data
└── setup.ts          # Test environment setup

Escrevendo Testes

  • Siga os padrões de teste existentes
  • Use nomes de teste descritivos
  • Simule dependências externas
  • Teste tanto os casos de sucesso quanto os de erro
  • Mantenha a cobertura de testes acima de 80%

Segurança

  • Tokens OAuth2 são criptografados em repouso
  • Todas as operações em massa exigem confirmação
  • Registro de auditoria para todas as operações
  • Limitação de taxa implementada para a API do Gmail
  • Rastreamento de padrões de acesso para monitoramento de segurança

Solução de Problemas

Problemas de Autenticação

  • Certifique-se de que credentials.json esteja no local correto
  • Verifique se a API do Gmail está ativada no GCP
  • Verifique se o URI de redirecionamento corresponde à sua configuração

Desempenho

  • A primeira categorização pode levar tempo para caixas de entrada grandes
  • Use paginação para grandes conjuntos de resultados
  • Ative o cache em produção

Licença

MIT

Contribuindo

Contribuições são bem-vindas! Leia nossas diretrizes de contribuição antes de enviar PRs.

🏗️ Visão Geral da Arquitetura

O Gmail MCP Server segue uma arquitetura modular em camadas, projetada para escalabilidade, manutenibilidade e extensibilidade.

Arquitetura Principal

graph TB
    subgraph "MCP Server Layer"
        MCP[MCP Server] --> TR[Tool Registry]
        TR --> AUTH[Auth Tools]
        TR --> EMAIL[Email Tools] 
        TR --> SEARCH[Search Tools]
        TR --> ARCHIVE[Archive Tools]
        TR --> DELETE[Delete Tools]
        TR --> JOB[Job Tools]
    end
    
    subgraph "Business Logic Layer"
        AUTH --> AM[Auth Manager]
        EMAIL --> EF[Email Fetcher]
        EMAIL --> CE[Categorization Engine]
        SEARCH --> SE[Search Engine]
        ARCHIVE --> ARM[Archive Manager]
        DELETE --> DM[Delete Manager]
        JOB --> JS[Job Status Store]
    end
    
    subgraph "Data Layer"
        AM --> DB[(SQLite Database)]
        CE --> DB
        SE --> DB
        ARM --> DB
        DM --> DB
        JS --> DB
        EF --> CACHE[Cache Manager]
    end
    
    subgraph "External Services"
        AM --> OAUTH[Google OAuth2]
        EF --> GMAIL[Gmail API]
        ARM --> CLOUD[Cloud Storage]
    end

Estrutura do Projeto

gmail-mcp-server/
├── 📁 src/
│   ├── 🔐 auth/                    # OAuth2 authentication & token management
│   │   └── AuthManager.ts          # Core authentication logic
│   ├── 📧 email/                   # Email processing & fetching
│   │   └── EmailFetcher.ts         # Gmail API integration
│   ├── 🧠 categorization/          # AI-powered email categorization
│   │   ├── CategorizationEngine.ts # Main categorization logic
│   │   ├── CategorizationWorker.ts # Background processing
│   │   └── analyzers/              # Specialized analyzers
│   │       ├── ImportanceAnalyzer.ts
│   │       ├── DateSizeAnalyzer.ts
│   │       └── LabelClassifier.ts
│   ├── 🔍 search/                  # Advanced search functionality
│   │   └── SearchEngine.ts         # Multi-criteria search
│   ├── 📁 archive/                 # Email archiving & export
│   │   └── ArchiveManager.ts       # Archive operations
│   ├── 🗑️ delete/                  # Safe email deletion
│   │   └── DeleteManager.ts        # Deletion with safety checks
│   ├── 🧹 cleanup/                 # Automated cleanup system
│   │   ├── CleanupAutomationEngine.ts
│   │   ├── CleanupPolicyEngine.ts
│   │   ├── StalenessScorer.ts
│   │   └── SystemHealthMonitor.ts
│   ├── 🛠️ tools/                   # MCP tool definitions
│   │   ├── ToolRegistry.ts         # Tool registration system
│   │   ├── definitions/            # Tool definitions by category
│   │   └── base/                   # Tool builder utilities
│   ├── 💾 database/                # Data persistence
│   │   ├── DatabaseManager.ts      # SQLite management
│   │   └── JobStatusStore.ts       # Job tracking
│   ├── ⚡ cache/                   # Performance caching
│   │   └── CacheManager.ts         # In-memory & persistent cache
│   └── 📊 types/                   # TypeScript definitions
│       └── index.ts                # Comprehensive type system
├── 📁 tests/                       # Comprehensive test suite
│   ├── unit/                       # Unit tests
│   ├── integration/                # Integration tests
│   └── performance/                # Performance tests
├── 📁 docs/                        # Documentation
├── 📁 scripts/                     # Utility scripts
└── 📁 examples/                    # Usage examples

Padrões de Design Principais

  • 🔧 Arquitetura Modular: Cada componente tem uma responsabilidade única
  • 🏭 Padrão de Fábrica: Criação de ferramentas e gerenciamento de configuração
  • 📦 Padrão de Repositório: Abstração de acesso a dados
  • 🔄 Padrão de Observador: Automação de limpeza orientada a eventos
  • 🛡️ Padrão de Estratégia: Múltiplos algoritmos de categorização
  • ⚡ Estratégia de Cache: Cache em vários níveis para desempenho

Fluxo de Dados

  1. Autenticação: Fluxo OAuth2 com armazenamento seguro de tokens
  2. Busca de E-mails: Processamento em lote com limitação de taxa da API do Gmail
  3. Categorização: Pipeline de múltiplos analisadores com pontuação semelhante a ML
  4. Busca: Busca indexada com combinações de filtros complexas
  5. Operações: Execução segura com etapas de simulação e confirmação

🔧 Desenvolvimento e Contribuição

Configuração de Desenvolvimento

# Clone and setup
git clone <repository-url>
cd gmail-mcp-server
npm install

# Development mode
npm run dev          # Hot reload with tsx
npm run watch        # TypeScript watch mode

# Testing
npm test            # Run all tests
npm run test:watch  # Watch mode testing
npm run inspector   # MCP Inspector for testing tools

Fluxo de Trabalho de Desenvolvimento

  1. 🌟 Desenvolvimento de Recursos

    # Create feature branch
git checkout -b feature/new-tool-name

# Make changes
# Add tests
# Update documentation

# Test thoroughly
npm test
npm run build

  2. 🧪 Estratégia de Testes

    • Testes Unitários: Testes de componentes individuais
    • Testes de Integração: Testes de fluxo de trabalho de ponta a ponta
    • Testes de Desempenho: Testes de carga e estresse
    • Testes Manuais: Validação com o MCP Inspector

  3. 📝 Documentação

    • Atualize o README.md para novas ferramentas
    • Adicione comentários JSDoc para APIs públicas
    • Inclua exemplos de uso
    • Atualize diagramas de arquitetura

Adicionando Novas Ferramentas MCP

  1. Criar Definição da Ferramenta

    // src/tools/definitions/my-category.tools.ts
export const myToolConfigs: ToolConfig[] = [
  {
    name: 'my_new_tool',
    description: 'Description of what the tool does',
    category: 'my_category',
    parameters: {
      required_param: ParameterTypes.string('Required parameter'),
      optional_param: ParameterTypes.boolean('Optional parameter', false)
    },
    required: ['required_param']
  }
];

  2. Implementar o Manipulador da Ferramenta

    // src/tools/handlers/my-tool.handler.ts
export async function handleMyNewTool(args: MyToolArgs): Promise<MyToolResult> {
  // Implementation
}

  3. Registrar a Ferramenta

    // src/tools/definitions/index.ts
import { myToolConfigs } from './my-category.tools.js';

export function registerAllTools() {
  myToolConfigs.forEach(config => {
    toolRegistry.registerTool(ToolBuilder.fromConfig(config), config.category);
  });
}

  4. Adicionar Testes

    // tests/unit/tools/my-tool.test.ts
describe('my_new_tool', () => {
  it('should handle valid input', async () => {
    // Test implementation
  });
});

Padrões de Qualidade de Código

  • 🔍 TypeScript: Verificação estrita de tipos com interfaces abrangentes
  • 📏 ESLint: Aplicação de estilo e qualidade de código
  • 🎯 Testes: Requisito de cobertura de testes >80%
  • 📚 Documentação: JSDoc para todas as APIs públicas
  • 🔒 Segurança: Validação e sanitização de entrada
  • ⚡ Desempenho: Algoritmos eficientes e cache

Diretrizes de Arquitetura

  • 🏗️ Separação de Preocupações: Cada módulo tem uma responsabilidade única
  • 🔌 Injeção de Dependência: Acoplamento fraco entre componentes
  • 📈 Escalabilidade: Projetado para grandes conjuntos de dados de e-mail
  • 🛡️ Tratamento de Erros: Tratamento e registro abrangentes de erros
  • 🔄 Operações Assíncronas: E/S sem bloqueio com limpeza adequada de recursos

Diretrizes de Contribuição

  1. 🎯 Problemas e Solicitações de Recursos

    • Use modelos de problemas
    • Forneça descrições detalhadas
    • Inclua casos de uso e exemplos

  2. 💻 Pull Requests

    • Siga o modelo de PR
    • Inclua testes e documentação
    • Garanta que a CI passe
    • Solicite revisões

  3. 📋 Lista de Verificação de Revisão de Código

    • ✅ Testes passam e cobertura mantida
    • ✅ Documentação atualizada
    • ✅ Segurança de tipos mantida
    • ✅ Considerações de segurança abordadas
    • ✅ Implicações de desempenho consideradas

Pontos de Extensão

O servidor é projetado para extensibilidade:

  • 🔧 Ferramentas Personalizadas: Adicione ferramentas específicas de domínio
  • 🧠 Analisadores: Implemente algoritmos de categorização personalizados
  • 📊 Exportadores: Adicione novos formatos de exportação
  • 🔍 Provedores de Busca: Integre mecanismos de busca externos
  • ☁️ Backends de Armazenamento: Adicione provedores de armazenamento em nuvem

📚 Exemplos de Fluxos de Trabalho

🚀 Configuração Inicial e Organização de E-mails

// 1. Authenticate with Gmail
{
  "tool": "authenticate"
}

// 2. Get initial statistics
{
  "tool": "get_email_stats",
  "arguments": {
    "group_by": "all"
  }
}

// 3. Categorize all emails (this may take time for large mailboxes)
{
  "tool": "categorize_emails",
  "arguments": {
    "year": 2024,
    "force_refresh": false
  }
}

// 4. Review categorization results
{
  "tool": "list_emails",
  "arguments": {
    "category": "high",
    "limit": 20
  }
}

🧹 Fluxo de Trabalho Avançado de Limpeza

// 1. Analyze old emails (dry run first)
{
  "tool": "search_emails",
  "arguments": {
    "year_range": { "end": 2022 },
    "size_range": { "min": 5242880 },
    "category": "low"
  }
}

// 2. Create archive rule for old large emails
{
  "tool": "create_archive_rule",
  "arguments": {
    "name": "Old Large Low Priority",
    "criteria": {
      "category": "low",
      "older_than_days": 365,
      "size_greater_than": 5242880
    },
    "action": {
      "method": "export",
      "export_format": "mbox"
    },
    "schedule": "monthly"
  }
}

// 3. Archive old emails (with dry run first)
{
  "tool": "archive_emails",
  "arguments": {
    "year": 2022,
    "category": "low",
    "method": "export",
    "export_format": "mbox",
    "dry_run": true
  }
}

// 4. Execute actual archival after reviewing dry run
{
  "tool": "archive_emails",
  "arguments": {
    "year": 2022,
    "category": "low",
    "method": "export",
    "export_format": "mbox",
    "dry_run": false
  }
}

🤖 Configuração de Política de Limpeza Automatizada

// 1. Create aggressive cleanup policy for spam
{
  "tool": "create_cleanup_policy",
  "arguments": {
    "name": "Spam Cleanup",
    "priority": 90,
    "criteria": {
      "age_days_min": 30,
      "importance_level_max": "low",
      "spam_score_min": 0.8
    },
    "action": {
      "type": "delete"
    },
    "safety": {
      "max_emails_per_run": 200,
      "dry_run_first": true
    }
  }
}

// 2. Create moderate policy for old promotional emails
{
  "tool": "create_cleanup_policy",
  "arguments": {
    "name": "Old Promotions Archive",
    "priority": 50,
    "criteria": {
      "age_days_min": 90,
      "importance_level_max": "low",
      "promotional_score_min": 0.7
    },
    "action": {
      "type": "archive",
      "method": "gmail"
    },
    "safety": {
      "max_emails_per_run": 100
    }
  }
}

// 3. Schedule nightly cleanup
{
  "tool": "create_cleanup_schedule",
  "arguments": {
    "name": "Nightly Cleanup",
    "type": "daily",
    "expression": "02:00",
    "policy_id": "spam_cleanup_policy_id"
  }
}

// 4. Monitor cleanup status
{
  "tool": "get_cleanup_status"
}

🔍 Busca e Análise Avançadas

// 1. Save frequently used searches
{
  "tool": "save_search",
  "arguments": {
    "name": "Large Recent Important",
    "criteria": {
      "category": "high",
      "year_range": { "start": 2024 },
      "size_range": { "min": 1048576 }
    }
  }
}

// 2. Search for specific patterns
{
  "tool": "search_emails",
  "arguments": {
    "query": "invoice OR receipt OR payment",
    "category": "high",
    "year_range": { "start": 2023 },
    "has_attachments": true
  }
}

// 3. Export search results
{
  "tool": "export_emails",
  "arguments": {
    "search_criteria": {
      "query": "invoice OR receipt",
      "year_range": { "start": 2023 }
    },
    "format": "csv",
    "include_attachments": false
  }
}

📊 Análises e Monitoramento

// 1. Get comprehensive statistics
{
  "tool": "get_email_stats",
  "arguments": {
    "group_by": "all"
  }
}

// 2. Monitor system health
{
  "tool": "get_system_health"
}

// 3. Get cleanup recommendations
{
  "tool": "get_cleanup_recommendations"
}

// 4. View cleanup metrics
{
  "tool": "get_cleanup_metrics",
  "arguments": {
    "hours": 168
  }
}

🔒 Segurança e Segurança

🛡️ Autenticação e Autorização

  • Fluxo OAuth2: Implementação segura do OAuth2 do Google
  • Criptografia de Tokens: Todos os tokens criptografados em repouso usando AES-256
  • Limitação de Escopo: Escopos mínimos necessários da API do Gmail
  • Rotação de Tokens: Atualização e rotação automática de tokens
  • Gerenciamento de Sessão: Tratamento seguro de sessões com expiração

🔐 Proteção de Dados

  • Armazenamento Local: Banco de dados SQLite criptografado para metadados
  • Sem Armazenamento de Conteúdo de E-mail: Apenas metadados armazenados localmente
  • Registro de Auditoria: Registro abrangente de operações
  • Isolamento de Dados: Dados do usuário completamente isolados
  • Comunicação Segura: HTTPS/TLS para todas as comunicações de API

⚠️ Mecanismos de Segurança

  1. Modo de Simulação: Todas as operações destrutivas suportam modo de pré-visualização
  2. Solicitações de Confirmação: Confirmação em várias etapas para operações em massa
  3. Limites de Segurança: Limites configuráveis de exclusão/modificação máxima
  4. Integração de Backup: Backup automático antes de operações importantes
  5. Capacidade de Reversão: Capacidade de restaurar a partir de arquivos

🚨 Mitigação de Riscos

  • Limitação de Taxa: Conformidade com a limitação de taxa da API do Gmail
  • Tratamento de Erros: Recuperação abrangente de erros
  • Validação: Sanitização e validação de entrada
  • Monitoramento: Monitoramento de operações em tempo real
  • Alertas: Alertas automáticos para problemas críticos

🔍 Melhores Práticas de Segurança

// Always use dry run first for destructive operations
{
  "tool": "delete_emails",
  "arguments": {
    "category": "low",
    "dry_run": true  // ← Always start with dry run
  }
}

// Limit operations with max_count
{
  "tool": "empty_trash",
  "arguments": {
    "max_count": 50,  // ← Safety limit
    "dry_run": true
  }
}

// Use specific criteria instead of broad deletions
{
  "tool": "delete_emails",
  "arguments": {
    "year": 2022,           // ← Specific year
    "category": "low",      // ← Specific category
    "size_threshold": 10485760,  // ← Specific size
    "max_count": 100,       // ← Safety limit
    "dry_run": true
  }
}

❓ Solução de Problemas

🔐 Problemas de Autenticação

Problema: Authentication failed ou Invalid credentials

# Solutions:
1. Verify credentials.json location (project root)
2. Check Gmail API is enabled in Google Cloud Console
3. Verify OAuth2 redirect URI matches configuration
4. Clear cached tokens: rm -rf data/tokens/
5. Re-run authentication: authenticate tool

Problema: Erros de Token expired

# Solutions:
1. Tokens auto-refresh, but if persistent:
2. Clear token cache: rm -rf data/tokens/
3. Re-authenticate: use authenticate tool
4. Check system clock is accurate

📧 Problemas de Processamento de E-mail

Problema: Categorization taking too long

# Solutions:
1. Use year-specific categorization:
   { "tool": "categorize_emails", "arguments": { "year": 2024 } }
2. Monitor progress:
   { "tool": "list_jobs", "arguments": { "status": "running" } }
3. Increase timeout in .env: CATEGORIZATION_TIMEOUT=300000

Problema: Search results incomplete

# Solutions:
1. Check Gmail API quota limits
2. Increase search limit: "limit": 500
3. Use pagination: "offset": 0, "limit": 100
4. Clear search cache: restart server

🗑️ Problemas de Exclusão e Limpeza

Problema: Deletion failed ou Cleanup stuck

# Solutions:
1. Always start with dry_run: true
2. Check job status: get_job_status
3. Cancel stuck jobs: cancel_job
4. Reduce max_count limits
5. Check Gmail API rate limits

Problema: Archives not restoring

# Solutions:
1. Check archive location exists
2. Verify archive format compatibility
3. Check available storage space
4. Use smaller batch sizes

⚡ Problemas de Desempenho

Problema: Slow search or categorization

# Solutions:
1. Enable caching: CACHE_ENABLED=true
2. Increase cache TTL: CACHE_TTL=7200
3. Use specific filters to reduce result sets
4. Consider database optimization: VACUUM

Problema: High memory usage

# Solutions:
1. Reduce batch sizes in operations
2. Clear cache periodically
3. Restart server regularly for large operations
4. Monitor with: get_system_health

📊 Problemas de Banco de Dados

Problema: Database locked ou SQLite errors

# Solutions:
1. Check for multiple server instances
2. Restart server to release locks
3. Check file permissions: data/ directory
4. Backup and recreate database if corrupted

🔧 Problemas de Desenvolvimento

Problema: MCP Inspector not working

# Solutions:
1. Install inspector: npm install -g @modelcontextprotocol/inspector
2. Build project first: npm run build
3. Run inspector: npm run inspector
4. Check server logs for errors

Problema: TypeScript compilation errors

# Solutions:
1. Clear build cache: rm -rf build/
2. Reinstall dependencies: npm ci
3. Check TypeScript version: npx tsc --version
4. Update dependencies: npm update

📞 Obtendo Ajuda

  • 📝 Documentação: Consulte o diretório docs/ para guias detalhados
  • 🐛 Problemas: Crie relatórios de problemas detalhados no GitHub
  • 💬 Discussões: Participe de discussões da comunidade
  • 🔍 Depuração: Ative o registro de depuração: LOG_LEVEL=debug

🚨 Procedimentos de Emergência

Se você excluir acidentalmente e-mails importantes:

  1. Verifique a pasta Lixeira do Gmail primeiro
  2. Use restore_emails se arquivado
  3. Verifique o banco de dados local para metadados
  4. Entre em contato com o suporte do Gmail para recuperação de conta

Se o sistema não responder:

  1. Cancele todas as tarefas em execução: cancel_job
  2. Reinicie o servidor: npm start
  3. Verifique a saúde do sistema: get_system_health
  4. Limpe os caches se necessário: rm -rf data/cache/

📄 Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

🤝 Contribuindo

Aceitamos contribuições! Consulte nossas Diretrizes de Contribuição para detalhes sobre:

  • 🐛 Relatórios de bugs e solicitações de recursos
  • 💻 Contribuições de código e pull requests
  • 📚 Melhorias na documentação
  • 🧪 Testes e garantia de qualidade
  • 🌍 Suporte à comunidade e discussões

⭐ Marque este projeto com uma estrela se você o achar útil!

GitHub stars Follow on X Follow on LinkedIn

Para executar a suíte de testes com eficiência, sempre defina a variável de ambiente NODE_ENV=test antes de executar os testes. Isso ativa o modo rápido, que:

  • Ignora atrasos artificiais (por exemplo, entre lotes)
  • Reduz a saída de registro para execuções de teste mais limpas e rápidas
  • Usa conjuntos de dados menores na maioria dos testes para velocidade (exceto testes de desempenho explícitos)

Exemplo:

NODE_ENV=test npm test

Ou com jest diretamente:

NODE_ENV=test npx jest

CI/CD:

Seu pipeline de CI deve sempre definir NODE_ENV=test para garantir a execução de testes mais rápida possível.