Gmail MCP Server

Un servidor MCP que se integra con la API de Gmail para la gestión inteligente de correos electrónicos, incluyendo búsqueda, categorización y archivado.

GitHub
2
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Gmail

Node.js Version License: MIT MCP Protocol TypeScript

Un servidor integral del Protocolo de Contexto de Modelos (MCP) que se integra con la API de Gmail para proporcionar capacidades inteligentes de gestión de correo electrónico. Incluye categorización avanzada de correos, búsqueda, archivado, eliminación y limpieza automatizada con más de 25 herramientas MCP para la gestión completa del ciclo de vida del correo electrónico.

🚀 Características Principales

📧 Gestión Inteligente de Correos

  • Categorización Impulsada por IA: Categoriza automáticamente los correos por importancia (alta/media/baja) mediante análisis avanzado
  • Búsqueda y Filtrado Inteligente: Búsqueda avanzada con múltiples criterios, búsquedas guardadas y combinaciones de filtros
  • Procesamiento en Tiempo Real: Procesamiento de trabajos en segundo plano para operaciones de larga duración con seguimiento de progreso

🗄️ Sistema de Archivado y Exportación

  • Archivado Inteligente: Archiva correos según reglas con múltiples formatos de exportación (MBOX, JSON, CSV)
  • Motor de Reglas Automatizadas: Crea y gestiona reglas automáticas de archivado con programación
  • Capacidad de Restauración: Restaura correos previamente archivados con metadatos completos

🧹 Automatización Avanzada de Limpieza

  • Limpieza Basada en Políticas: Más de 13 herramientas de limpieza con políticas configurables para la gestión automatizada de correos
  • Seguimiento de Patrones de Acceso: Rastrea patrones de acceso a correos para decisiones inteligentes de limpieza
  • Diseño Priorizando la Seguridad: Opciones de simulación, pasos de confirmación y capacidades de reversión

📊 Analíticas y Monitoreo

  • Estadísticas Integrales: Analíticas detalladas de uso de correos por categoría, año, tamaño y más
  • Monitoreo de Salud del Sistema: Métricas en tiempo real, seguimiento de rendimiento e informes de salud del sistema
  • Recomendaciones de Limpieza: Recomendaciones impulsadas por IA para una gestión óptima de correos

🔒 Seguridad y Protección

  • Autenticación OAuth2: Integración segura con la API de Gmail con almacenamiento cifrado de tokens
  • Seguridad Multicapa: Avisos de confirmación, modos de simulación y límites máximos de eliminación
  • Registro de Auditoría: Registro completo de operaciones y seguimiento de errores

📋 Tabla de Contenidos

🚀 Inicio Rápido

Requisitos Previos

  • Node.js 18+ y npm
  • Cuenta de Google Cloud Platform con la API de Gmail habilitada
  • Credenciales OAuth2 (ID de Cliente y Secreto de Cliente)

Configuración Automatizada

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

Primera Ejecución

# Start the MCP server
npm start

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

📦 Instalación

Método 1: Configuración 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

El script de configuración te guiará a través de:

  • 🔑 Configuración de credenciales de Google Cloud
  • 📁 Creación de directorios necesarios
  • ⚙️ Configuración de variables de entorno
  • 🔧 Configuración inicial

Método 2: Configuración Manual

  1. Configura las credenciales de Google Cloud:

    • Ve a Consola de Google Cloud
    • Crea un proyecto o selecciona uno existente
    • Habilita la API de Gmail
    • Crea credenciales OAuth2 (aplicación de escritorio)
    • Descarga credentials.json a la raíz del proyecto

  2. Configura el entorno:

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

  3. Crea los directorios:

    mkdir -p data logs archives

  4. Instala y compila:

    npm install
npm run build

🔧 Configuración

Configuración del Cliente MCP

Para Claude Desktop:

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

Para otros clientes MCP:

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

Configuración del Entorno

Variables de entorno clave en .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

🛠️ Referencia de Herramientas MCP

El Servidor MCP de Gmail proporciona más de 25 herramientas especializadas organizadas en categorías lógicas para la gestión integral de correos electrónicos. Cada herramienta incluye funciones de seguridad, validación de parámetros y manejo detallado de errores.

🔐 Herramientas de Autenticación

authenticate

Inicia el flujo de autenticación OAuth2 con la API de Gmail.

Parámetros:

  • scopes (matriz, opcional): Alcances OAuth adicionales más allá de lectura/escritura de Gmail

Devuelve: Estado de autenticación y correo electrónico del usuario

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

📧 Herramientas de Gestión de Correos

list_emails

Lista correos con filtrado y paginación integrales.

Parámetros:

  • category (cadena): Filtra por nivel de importancia (high|medium|low)
  • year (número): Filtra por año específico
  • size_min (número): Tamaño mínimo en bytes
  • size_max (número): Tamaño máximo en bytes
  • archived (booleano): Incluir correos archivados
  • has_attachments (booleano): Filtrar por presencia de adjuntos
  • labels (matriz): Filtrar por etiquetas de Gmail
  • query (cadena): Cadena de consulta personalizada de Gmail
  • limit (número, predeterminado: 50): Resultados máximos
  • offset (número, predeterminado: 0): Omitir los primeros N resultados
{
  "tool": "list_emails",
  "arguments": {
    "category": "high",
    "year": 2024,
    "has_attachments": true,
    "limit": 25
  }
}

get_email_details

Recupera el contenido completo del correo y sus metadatos.

Parámetros:

  • id (cadena, obligatorio): ID del mensaje de Gmail

Devuelve: Objeto de correo completo con encabezados, cuerpo y adjuntos

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

categorize_emails

Analiza y categoriza correos por importancia mediante algoritmos de IA.

Parámetros:

  • year (número, obligatorio): Año a categorizar
  • force_refresh (booleano): Reanalizar correos ya categorizados

Devuelve: Estado del trabajo de categorización y estadísticas

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

🔍 Herramientas de Búsqueda y Filtrado

search_emails

Búsqueda avanzada de correos con múltiples criterios y filtrado inteligente.

Parámetros:

  • query (cadena): Consulta de búsqueda de texto
  • category (cadena): Filtro de importancia (high|medium|low)
  • year_range (objeto): Rango de fechas con año de start y/o end
  • size_range (objeto): Rango de tamaño con min y/o max bytes
  • sender (cadena): Filtrar por dirección de correo del remitente
  • has_attachments (booleano): Filtro de presencia de adjuntos
  • archived (booleano): Incluir correos archivados
  • limit (número, predeterminado: 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

Guarda criterios de búsqueda para reutilización rápida.

Parámetros:

  • name (cadena, obligatorio): Nombre para la búsqueda guardada
  • criteria (objeto, obligatorio): Criterios de búsqueda a guardar
{
  "tool": "save_search",
  "arguments": {
    "name": "Large Recent Emails",
    "criteria": {
      "size_range": { "min": 5242880 },
      "year_range": { "start": 2024 }
    }
  }
}

list_saved_searches

Recupera todas las consultas de búsqueda guardadas.

Parámetros: Ninguno

Devuelve: Matriz de búsquedas guardadas con estadísticas de uso

{
  "tool": "list_saved_searches"
}

📁 Herramientas de Archivado y Exportación

archive_emails

Archiva correos utilizando múltiples métodos y formatos.

Parámetros:

  • search_criteria (objeto): Criterios de selección de correos
  • category (cadena): Archivar por nivel de importancia
  • year (número): Archivar correos de un año específico
  • older_than_days (número): Archivar correos con más de N días de antigüedad
  • method (cadena, obligatorio): Método de archivado (gmail|export)
  • export_format (cadena): Formato al exportar (mbox|json)
  • export_path (cadena): Destino de exportación personalizado
  • dry_run (booleano, predeterminado: falso): Modo de vista previa
{
  "tool": "archive_emails",
  "arguments": {
    "category": "low",
    "older_than_days": 180,
    "method": "export",
    "export_format": "mbox",
    "dry_run": false
  }
}

restore_emails

Restaura correos desde archivos anteriores.

Parámetros:

  • archive_id (cadena): Archivo específico desde el cual restaurar
  • email_ids (matriz): IDs de correos individuales a restaurar
  • restore_labels (matriz): Etiquetas a aplicar a los correos restaurados
{
  "tool": "restore_emails",
  "arguments": {
    "archive_id": "archive_2023_low_priority",
    "restore_labels": ["restored", "reviewed"]
  }
}

create_archive_rule

Crea reglas automáticas de archivado con programación.

Parámetros:

  • name (cadena, obligatorio): Nombre descriptivo de la regla
  • criteria (objeto, obligatorio): Condiciones de archivado
  • action (objeto, obligatorio): Método y formato de archivado
  • schedule (cadena): Frecuencia de ejecución (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

Muestra todas las reglas de archivado configuradas y su estado.

Parámetros:

  • active_only (booleano, predeterminado: falso): Mostrar solo reglas habilitadas
{
  "tool": "list_archive_rules",
  "arguments": {
    "active_only": true
  }
}

export_emails

Exporta correos a formatos externos con soporte de carga en la nube.

Parámetros:

  • search_criteria (objeto): Filtros de selección de correos
  • format (cadena, obligatorio): Formato de exportación (mbox|json|csv)
  • include_attachments (booleano, predeterminado: falso): Incluir adjuntos
  • output_path (cadena): Ruta de salida local
  • cloud_upload (objeto): Configuración de almacenamiento en la nube
{
  "tool": "export_emails",
  "arguments": {
    "format": "json",
    "search_criteria": { "year": 2023 },
    "include_attachments": true,
    "cloud_upload": {
      "provider": "gdrive",
      "path": "/backups/gmail-2023"
    }
  }
}

🗑️ Herramientas de Eliminación y Limpieza

delete_emails

Elimina correos de forma segura con verificaciones de seguridad integrales.

⚠️ Nota de Seguridad: Utiliza siempre dry_run: true primero para previsualizar las eliminaciones

Parámetros:

  • search_criteria (objeto): Filtros de selección de correos
  • category (cadena): Eliminar por nivel de importancia
  • year (número): Eliminar de un año específico
  • size_threshold (número): Eliminar correos mayores a N bytes
  • skip_archived (booleano, predeterminado: verdadero): Omitir correos archivados
  • dry_run (booleano, predeterminado: falso): Modo de vista previa
  • max_count (número, predeterminado: 10): Límite de seguridad
{
  "tool": "delete_emails",
  "arguments": {
    "category": "low",
    "year": 2022,
    "dry_run": true,
    "max_count": 50
  }
}

empty_trash

Elimina permanentemente todos los correos en la carpeta de papelera de Gmail.

⚠️ Operación Destructiva: Esto elimina correos permanentemente

Parámetros:

  • dry_run (booleano, predeterminado: falso): Modo de vista previa
  • max_count (número, predeterminado: 10): Límite de seguridad
{
  "tool": "empty_trash",
  "arguments": {
    "dry_run": true,
    "max_count": 100
  }
}

trigger_cleanup

Ejecuta limpieza manual utilizando políticas específicas.

Parámetros:

  • policy_id (cadena, obligatorio): Política de limpieza a ejecutar
  • dry_run (booleano, predeterminado: falso): Modo de vista previa
  • max_emails (número): Límite de procesamiento
  • force (booleano, predeterminado: falso): Ejecutar incluso si la política está deshabilitada
{
  "tool": "trigger_cleanup",
  "arguments": {
    "policy_id": "old_low_priority_emails",
    "dry_run": true,
    "max_emails": 500
  }
}

get_cleanup_status

Monitorea el estado del sistema de automatización de limpieza.

Parámetros: Ninguno

Devuelve: Estado del sistema, trabajos activos y métricas de salud

{
  "tool": "get_cleanup_status"
}

get_system_health

Obtiene métricas integrales de salud del sistema y rendimiento.

Parámetros: Ninguno

Devuelve: Métricas de rendimiento, uso de almacenamiento y estado del sistema

{
  "tool": "get_system_health"
}

create_cleanup_policy

Crea políticas avanzadas de limpieza con criterios detallados.

Parámetros:

  • name (cadena, obligatorio): Nombre de la política
  • enabled (booleano, predeterminado: verdadero): Estado de la política
  • priority (número, predeterminado: 50): Prioridad de ejecución (0-100)
  • criteria (objeto, obligatorio): Condiciones de limpieza
  • action (objeto, obligatorio): Acción a tomar
  • safety (objeto, obligatorio): Configuración de seguridad
  • schedule (objeto): Programación 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 la configuración de una política de limpieza existente.

Parámetros:

  • policy_id (cadena, obligatorio): Política a actualizar
  • updates (objeto, obligatorio): Cambios a aplicar
{
  "tool": "update_cleanup_policy",
  "arguments": {
    "policy_id": "policy_123",
    "updates": {
      "enabled": false,
      "safety": { "max_emails_per_run": 50 }
    }
  }
}

list_cleanup_policies

Muestra todas las políticas de limpieza y sus configuraciones.

Parámetros:

  • active_only (booleano, predeterminado: falso): Mostrar solo políticas habilitadas
{
  "tool": "list_cleanup_policies",
  "arguments": {
    "active_only": true
  }
}

delete_cleanup_policy

Elimina una política de limpieza permanentemente.

Parámetros:

  • policy_id (cadena, obligatorio): Política a eliminar
{
  "tool": "delete_cleanup_policy",
  "arguments": {
    "policy_id": "outdated_policy_456"
  }
}

create_cleanup_schedule

Programa la ejecución automática de políticas de limpieza. Parámetros:

  • name (cadena, obligatorio): Nombre del programa
  • type (cadena, obligatorio): Tipo de programa (daily|weekly|monthly|interval|cron)
  • expression (cadena, obligatorio): Expresión del programa
  • policy_id (cadena, obligatorio): Política a programar
  • enabled (booleano, predeterminado: true): Estado del programa
{
  "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

Actualizar la configuración global de automatización de limpieza.

Parámetros:

  • config (objeto, obligatorio): Actualizaciones de configuración
{
  "tool": "update_cleanup_automation_config",
  "arguments": {
    "config": {
      "continuous_cleanup": {
        "enabled": true,
        "target_emails_per_minute": 10
      }
    }
  }
}

get_cleanup_metrics

Recuperar análisis y datos de rendimiento del sistema de limpieza.

Parámetros:

  • hours (número, predeterminado: 24): Ventana de historial en horas
{
  "tool": "get_cleanup_metrics",
  "arguments": {
    "hours": 168
  }
}

get_cleanup_recommendations

Obtener recomendaciones de políticas de limpieza impulsadas por IA.

Parámetros: Ninguno

Devuelve: Políticas recomendadas basadas en el análisis de correos electrónicos

{
  "tool": "get_cleanup_recommendations"
}

📊 Herramientas de Estadísticas y Análisis

get_email_stats

Estadísticas y análisis completos del uso del correo electrónico.

Parámetros:

  • group_by (cadena): Método de agrupación (year|category|label|all)
  • year (número): Filtrar por año específico

Devuelve: Estadísticas detalladas por categorías, años, tamaños y almacenamiento

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

⚙️ Herramientas de Gestión de Trabajos

list_jobs

Ver todos los trabajos en segundo plano con opciones de filtrado.

Parámetros:

  • limit (número, predeterminado: 50): Resultados máximos
  • offset (número, predeterminado: 0): Omitir los primeros N trabajos
  • status (cadena): Filtrar por estado (pending|running|completed|failed)
  • job_type (cadena): Filtrar por tipo de trabajo
{
  "tool": "list_jobs",
  "arguments": {
    "status": "running",
    "limit": 25
  }
}

get_job_status

Obtener el estado detallado de un trabajo en segundo plano específico.

Parámetros:

  • id (cadena, obligatorio): ID del trabajo a consultar

Devuelve: Detalles del trabajo, progreso y resultados

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

cancel_job

Cancelar un trabajo en segundo plano en ejecución.

Parámetros:

  • id (cadena, obligatorio): ID del trabajo a cancelar
{
  "tool": "cancel_job",
  "arguments": {
    "id": "cleanup_job_101112"
  }
}

Flujos de Trabajo de Ejemplo

Configuración 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"
  }
}

Limpiar Correos Electrónicos Antiguos

// 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"
  }
}

Configuración de Limpieza 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"
}

Desarrollo

Estructura del Proyecto

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

Ejecución en Desarrollo

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

Pruebas con MCP Inspector

npm run inspector

Pruebas

El proyecto incluye conjuntos de pruebas completos para garantizar la fiabilidad y corrección de todas las funciones.

Ejecución de Pruebas

# Run all tests
npm test

# Run with coverage
npm test -- --coverage

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

Pruebas de Integración

Pruebas de Eliminación de Correos Electrónicos

La funcionalidad de eliminación tiene pruebas de integración exhaustivas que cubren todos los escenarios:

# 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 información detallada sobre las pruebas de eliminación de correos electrónicos, consulte Documentación de Pruebas de Eliminación de Correos Electrónicos.

Estructura de Pruebas

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

Escritura de Pruebas

  • Siga los patrones de prueba existentes
  • Utilice nombres de prueba descriptivos
  • Simule dependencias externas
  • Pruebe tanto casos de éxito como de error
  • Mantenga la cobertura de pruebas por encima del 80%

Seguridad

  • Los tokens OAuth2 están cifrados en reposo
  • Todas las operaciones masivas requieren confirmación
  • Registro de auditoría para todas las operaciones
  • Limitación de velocidad implementada para la API de Gmail
  • Seguimiento de patrones de acceso para monitoreo de seguridad

Solución de Problemas

Problemas de Autenticación

  • Asegúrese de que credentials.json esté en la ubicación correcta
  • Verifique que la API de Gmail esté habilitada en GCP
  • Verifique que la URI de redirección coincida con su configuración

Rendimiento

  • La primera categorización puede tardar en buzones grandes
  • Utilice paginación para conjuntos de resultados grandes
  • Habilite el almacenamiento en caché en producción

Licencia

MIT

Contribuciones

¡Las contribuciones son bienvenidas! Lea nuestras pautas de contribución antes de enviar PRs.

🏗️ Descripción General de la Arquitectura

El Gmail MCP Server sigue una arquitectura modular y en capas diseñada para escalabilidad, mantenibilidad y extensibilidad.

Arquitectura 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

Estructura del Proyecto

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

Patrones de Diseño Clave

  • 🔧 Arquitectura Modular: Cada componente tiene una responsabilidad única
  • 🏭 Patrón de Fábrica: Creación de herramientas y gestión de configuración
  • 📦 Patrón de Repositorio: Abstracción de acceso a datos
  • 🔄 Patrón de Observador: Automatización de limpieza basada en eventos
  • 🛡️ Patrón de Estrategia: Múltiples algoritmos de categorización
  • ⚡ Estrategia de Caché: Caché multinivel para rendimiento

Flujo de Datos

  1. Autenticación: Flujo OAuth2 con almacenamiento seguro de tokens
  2. Obtención de Correos Electrónicos: Procesamiento por lotes con limitación de velocidad de la API de Gmail
  3. Categorización: Canalización de múltiples analizadores con puntuación tipo ML
  4. Búsqueda: Búsqueda indexada con combinaciones de filtros complejas
  5. Operaciones: Ejecución segura con pasos de simulación y confirmación

🔧 Desarrollo y Contribuciones

Configuración de Desarrollo

# 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

Flujo de Trabajo de Desarrollo

  1. 🌟 Desarrollo de Funciones

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

# Make changes
# Add tests
# Update documentation

# Test thoroughly
npm test
npm run build

  2. 🧪 Estrategia de Pruebas

    • Pruebas Unitarias: Pruebas de componentes individuales
    • Pruebas de Integración: Pruebas de flujo de trabajo de extremo a extremo
    • Pruebas de Rendimiento: Pruebas de carga y estrés
    • Pruebas Manuales: Validación con MCP Inspector

  3. 📝 Documentación

    • Actualice README.md para nuevas herramientas
    • Agregue comentarios JSDoc para APIs públicas
    • Incluya ejemplos de uso
    • Actualice los diagramas de arquitectura

Agregar Nuevas Herramientas MCP

  1. Crear Definición de Herramienta

    // 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 Manejador de Herramienta

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

  3. Registrar Herramienta

    // 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. Agregar Pruebas

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

Estándares de Calidad de Código

  • 🔍 TypeScript: Verificación estricta de tipos con interfaces completas
  • 📏 ESLint: Aplicación de estilo y calidad de código
  • 🎯 Pruebas: Requisito de cobertura de pruebas >80%
  • 📚 Documentación: JSDoc para todas las APIs públicas
  • 🔒 Seguridad: Validación y saneamiento de entradas
  • ⚡ Rendimiento: Algoritmos eficientes y almacenamiento en caché

Pautas de Arquitectura

  • 🏗️ Separación de Preocupaciones: Cada módulo tiene una responsabilidad única
  • 🔌 Inyección de Dependencias: Acoplamiento flexible entre componentes
  • 📈 Escalabilidad: Diseñado para grandes conjuntos de datos de correo electrónico
  • 🛡️ Manejo de Errores: Manejo y registro de errores completo
  • 🔄 Operaciones Asíncronas: E/S sin bloqueo con limpieza adecuada de recursos

Pautas de Contribución

  1. 🎯 Problemas y Solicitudes de Funciones

    • Utilice plantillas de problemas
    • Proporcione descripciones detalladas
    • Incluya casos de uso y ejemplos

  2. 💻 Solicitudes de Extracción

    • Siga la plantilla de PR
    • Incluya pruebas y documentación
    • Asegúrese de que CI pase
    • Solicite revisiones

  3. 📋 Lista de Verificación de Revisión de Código

    • ✅ Las pruebas pasan y se mantiene la cobertura
    • ✅ Documentación actualizada
    • ✅ Seguridad de tipos mantenida
    • ✅ Consideraciones de seguridad abordadas
    • ✅ Implicaciones de rendimiento consideradas

Puntos de Extensión

El servidor está diseñado para extensibilidad:

  • 🔧 Herramientas Personalizadas: Agregue herramientas específicas de dominio
  • 🧠 Analizadores: Implemente algoritmos de categorización personalizados
  • 📊 Exportadores: Agregue nuevos formatos de exportación
  • 🔍 Proveedores de Búsqueda: Integre motores de búsqueda externos
  • ☁️ Backends de Almacenamiento: Agregue proveedores de almacenamiento en la nube

📚 Flujos de Trabajo de Ejemplo

🚀 Configuración Inicial y Organización de Correos Electrónicos

// 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
  }
}

🧹 Flujo de Trabajo Avanzado de Limpieza

// 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
  }
}

🤖 Configuración de Políticas de Limpieza 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"
}

🔍 Búsqueda y Análisis Avanzados

// 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álisis y Monitoreo

// 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
  }
}

🔒 Seguridad y Protección

🛡️ Autenticación y Autorización

  • Flujo OAuth2: Implementación segura de OAuth2 de Google
  • Cifrado de Tokens: Todos los tokens cifrados en reposo usando AES-256
  • Limitación de Alcances: Alcances mínimos requeridos de la API de Gmail
  • Rotación de Tokens: Actualización y rotación automática de tokens
  • Gestión de Sesiones: Manejo seguro de sesiones con expiración

🔐 Protección de Datos

  • Almacenamiento Local: Base de datos SQLite cifrada para metadatos
  • Sin Almacenamiento de Contenido de Correos: Solo se almacenan metadatos localmente
  • Registro de Auditoría: Registro completo de operaciones
  • Aislamiento de Datos: Datos de usuario completamente aislados
  • Comunicación Segura: HTTPS/TLS para todas las comunicaciones de API

⚠️ Mecanismos de Seguridad

  1. Modo de Simulación: Todas las operaciones destructivas admiten modo de vista previa
  2. Solicitudes de Confirmación: Confirmación de múltiples pasos para operaciones masivas
  3. Límites de Seguridad: Límites máximos configurables de eliminación/modificación
  4. Integración de Copias de Seguridad: Copia de seguridad automática antes de operaciones importantes
  5. Capacidad de Reversión: Capacidad de restaurar desde archivos

🚨 Mitigación de Riesgos

  • Limitación de Velocidad: Cumplimiento de la limitación de velocidad de la API de Gmail
  • Manejo de Errores: Recuperación completa de errores
  • Validación: Saneamiento y validación de entradas
  • Monitoreo: Monitoreo de operaciones en tiempo real
  • Alertas: Alertas automáticas para problemas críticos

🔍 Mejores Prácticas de Seguridad

// 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
  }
}

❓ Solución de Problemas

🔐 Problemas de Autenticación

Problema: Authentication failed o 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: Errores 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 Procesamiento de Correos Electrónicos

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 Eliminación y Limpieza

Problema: Deletion failed o 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 Rendimiento

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 Base de Datos

Problema: Database locked o 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 Desarrollo

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

📞 Obtención de Ayuda

  • 📝 Documentación: Consulte el directorio docs/ para guías detalladas
  • 🐛 Problemas: Cree informes de problemas detallados en GitHub
  • 💬 Discusiones: Únase a las discusiones de la comunidad
  • 🔍 Depuración: Habilite el registro de depuración: LOG_LEVEL=debug

🚨 Procedimientos de Emergencia

Si elimina accidentalmente correos electrónicos importantes:

  1. Verifique primero la carpeta de Papelera de Gmail
  2. Use restore_emails si está archivado
  3. Verifique la base de datos local para metadatos
  4. Contacte al soporte de Gmail para recuperación de cuenta

Si el sistema no responde:

  1. Cancele todos los trabajos en ejecución: cancel_job
  2. Reinicie el servidor: npm start
  3. Verifique el estado del sistema: get_system_health
  4. Limpie las cachés si es necesario: rm -rf data/cache/

📄 Licencia

Licencia MIT - consulte el archivo LICENCIA para más detalles.

🤝 Contribuciones

¡Damos la bienvenida a las contribuciones! Consulte nuestras Pautas de Contribución para más detalles sobre:

  • 🐛 Informes de errores y solicitudes de funciones
  • 💻 Contribuciones de código y solicitudes de extracción
  • 📚 Mejoras de documentación
  • 🧪 Pruebas y aseguramiento de calidad
  • 🌍 Soporte comunitario y discusiones

⭐ ¡Marque este proyecto con una estrella si le resulta útil!

GitHub stars Follow on X Follow on LinkedIn

Para ejecutar el conjunto de pruebas de manera eficiente, siempre establezca la variable de entorno NODE_ENV=test antes de ejecutar las pruebas. Esto habilita el modo rápido, que:

  • Omite retrasos artificiales (por ejemplo, entre lotes)
  • Reduce la salida de registro para ejecuciones de pruebas más limpias y rápidas
  • Utiliza conjuntos de datos más pequeños en la mayoría de las pruebas para velocidad (excepto pruebas de rendimiento explícitas)

Ejemplo:

NODE_ENV=test npm test

O con jest directamente:

NODE_ENV=test npx jest

CI/CD:

Su canalización de CI siempre debe establecer NODE_ENV=test para garantizar la ejecución de pruebas más rápida posible.