Gmail MCP Server
A comprehensive Model Context Protocol (MCP) server that integrates with Gmail API to provide intelligent email management capabilities. Features advanced email categorization, search, archiving, deletion, and automated cleanup with 25+ MCP tools for complete email lifecycle management.
🚀 Key Features
📧 Intelligent Email Management
- AI-Powered Categorization: Automatically categorize emails by importance (high/medium/low) using advanced analysis
- Smart Search & Filtering: Advanced search with multiple criteria, saved searches, and filter combinations
- Real-time Processing: Background job processing for long-running operations with progress tracking
🗄️ Archive & Export System
- Smart Archiving: Archive emails based on rules with multiple export formats (MBOX, JSON, CSV)
- Automated Rules Engine: Create and manage automatic archiving rules with scheduling
- Restore Capability: Restore previously archived emails with full metadata
🧹 Advanced Cleanup Automation
- Policy-Based Cleanup: 13+ cleanup tools with configurable policies for automated email management
- Access Pattern Tracking: Track email access patterns for intelligent cleanup decisions
- Safety-First Design: Dry-run options, confirmation steps, and rollback capabilities
📊 Analytics & Monitoring
- Comprehensive Statistics: Detailed email usage analytics by category, year, size, and more
- System Health Monitoring: Real-time metrics, performance tracking, and system health reports
- Cleanup Recommendations: AI-driven recommendations for optimal email management
🔒 Security & Safety
- OAuth2 Authentication: Secure Gmail API integration with encrypted token storage
- Multi-layered Safety: Confirmation prompts, dry-run modes, and maximum deletion limits
- Audit Logging: Complete operation logging and error tracking
📋 Table of Contents
- 🚀 Quick Start
- 📦 Installation
- 🔧 Configuration
- 🛠️ MCP Tools Reference
- 🏗️ Architecture Overview
- 🔧 Development & Contributing
- 📚 Example Workflows
- 🔒 Security & Safety
- ❓ Troubleshooting
🚀 Quick Start
Prerequisites
- Node.js 18+ and npm
- Google Cloud Platform account with Gmail API enabled
- OAuth2 credentials (Client ID and Client Secret)
Automated Setup
# Clone and install
git clone <repository-url>
cd gmail-mcp-server
npm run setup # Interactive setup wizard
npm install && npm run build
First Run
# Start the MCP server
npm start
# Authenticate with Gmail (run in your MCP client)
{
"tool": "authenticate"
}
📦 Installation
Method 1: Quick Setup (Recommended)
# 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
The setup script will guide you through:
- 🔑 Setting up Google Cloud credentials
- 📁 Creating necessary directories
- ⚙️ Configuring environment variables
- 🔧 Initial configuration
Method 2: Manual Setup
-
Set up Google Cloud credentials:
- Go to Google Cloud Console
- Create project or select existing
- Enable Gmail API
- Create OAuth2 credentials (Desktop application)
- Download
credentials.jsonto project root
-
Configure environment:
cp .env.example .env # Edit .env with your settings -
Create directories:
mkdir -p data logs archives -
Install and build:
npm install npm run build
🔧 Configuration
MCP Client Setup
For Claude Desktop:
{
"mcpServers": {
"gmail": {
"command": "node",
"args": ["/path/to/gmail-mcp-server/build/index.js"],
"env": {
"NODE_ENV": "production"
}
}
}
}
For other MCP clients:
# Direct stdio connection
node /path/to/gmail-mcp-server/build/index.js
Environment Configuration
Key environment variables in .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
🛠️ MCP Tools Reference
The Gmail MCP Server provides 25+ specialized tools organized into logical categories for comprehensive email management. Each tool includes safety features, parameter validation, and detailed error handling.
🔐 Authentication Tools
authenticate
Initiates OAuth2 authentication flow with Gmail API.
Parameters:
scopes(array, optional): Additional OAuth scopes beyond Gmail read/write
Returns: Authentication status and user email
{
"tool": "authenticate",
"arguments": {
"scopes": ["https://www.googleapis.com/auth/gmail.modify"]
}
}
📧 Email Management Tools
list_emails
List emails with comprehensive filtering and pagination.
Parameters:
category(string): Filter by importance level (high|medium|low)year(number): Filter by specific yearsize_min(number): Minimum size in bytessize_max(number): Maximum size in bytesarchived(boolean): Include archived emailshas_attachments(boolean): Filter by attachment presencelabels(array): Filter by Gmail labelsquery(string): Custom Gmail query stringlimit(number, default: 50): Maximum resultsoffset(number, default: 0): Skip first N results
{
"tool": "list_emails",
"arguments": {
"category": "high",
"year": 2024,
"has_attachments": true,
"limit": 25
}
}
get_email_details
Retrieve complete email content and metadata.
Parameters:
id(string, required): Gmail message ID
Returns: Full email object with headers, body, attachments
{
"tool": "get_email_details",
"arguments": {
"id": "18c2e4f5d9a8b7c3"
}
}
categorize_emails
Analyze and categorize emails by importance using AI algorithms.
Parameters:
year(number, required): Year to categorizeforce_refresh(boolean): Re-analyze already categorized emails
Returns: Categorization job status and statistics
{
"tool": "categorize_emails",
"arguments": {
"year": 2024,
"force_refresh": true
}
}
🔍 Search & Filter Tools
search_emails
Advanced multi-criteria email search with intelligent filtering.
Parameters:
query(string): Text search querycategory(string): Importance filter (high|medium|low)year_range(object): Date range withstartand/orendyearsize_range(object): Size range withminand/ormaxbytessender(string): Filter by sender email addresshas_attachments(boolean): Attachment presence filterarchived(boolean): Include archived emailslimit(number, default: 50): Maximum results
{
"tool": "search_emails",
"arguments": {
"query": "project deadline",
"category": "high",
"year_range": { "start": 2024 },
"size_range": { "min": 1048576 },
"sender": "manager@company.com"
}
}
save_search
Save search criteria for quick reuse.
Parameters:
name(string, required): Name for saved searchcriteria(object, required): Search criteria to save
{
"tool": "save_search",
"arguments": {
"name": "Large Recent Emails",
"criteria": {
"size_range": { "min": 5242880 },
"year_range": { "start": 2024 }
}
}
}
list_saved_searches
Retrieve all saved search queries.
Parameters: None
Returns: Array of saved searches with usage statistics
{
"tool": "list_saved_searches"
}
📁 Archive & Export Tools
archive_emails
Archive emails using multiple methods and formats.
Parameters:
search_criteria(object): Email selection criteriacategory(string): Archive by importance levelyear(number): Archive emails from specific yearolder_than_days(number): Archive emails older than N daysmethod(string, required): Archive method (gmail|export)export_format(string): Format when exporting (mbox|json)export_path(string): Custom export destinationdry_run(boolean, default: false): Preview mode
{
"tool": "archive_emails",
"arguments": {
"category": "low",
"older_than_days": 180,
"method": "export",
"export_format": "mbox",
"dry_run": false
}
}
restore_emails
Restore emails from previous archives.
Parameters:
archive_id(string): Specific archive to restore fromemail_ids(array): Individual email IDs to restorerestore_labels(array): Labels to apply to restored emails
{
"tool": "restore_emails",
"arguments": {
"archive_id": "archive_2023_low_priority",
"restore_labels": ["restored", "reviewed"]
}
}
create_archive_rule
Create automated archiving rules with scheduling.
Parameters:
name(string, required): Descriptive rule namecriteria(object, required): Archiving conditionsaction(object, required): Archive method and formatschedule(string): Execution frequency (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
View all configured archive rules and their status.
Parameters:
active_only(boolean, default: false): Show only enabled rules
{
"tool": "list_archive_rules",
"arguments": {
"active_only": true
}
}
export_emails
Export emails to external formats with cloud upload support.
Parameters:
search_criteria(object): Email selection filtersformat(string, required): Export format (mbox|json|csv)include_attachments(boolean, default: false): Include attachmentsoutput_path(string): Local output pathcloud_upload(object): Cloud storage configuration
{
"tool": "export_emails",
"arguments": {
"format": "json",
"search_criteria": { "year": 2023 },
"include_attachments": true,
"cloud_upload": {
"provider": "gdrive",
"path": "/backups/gmail-2023"
}
}
}
🗑️ Delete & Cleanup Tools
delete_emails
Safely delete emails with comprehensive safety checks.
⚠️ Safety Note: Always use dry_run: true first to preview deletions
Parameters:
search_criteria(object): Email selection filterscategory(string): Delete by importance levelyear(number): Delete from specific yearsize_threshold(number): Delete emails larger than N bytesskip_archived(boolean, default: true): Skip archived emailsdry_run(boolean, default: false): Preview modemax_count(number, default: 10): Safety limit
{
"tool": "delete_emails",
"arguments": {
"category": "low",
"year": 2022,
"dry_run": true,
"max_count": 50
}
}
empty_trash
Permanently delete all emails in Gmail trash folder.
⚠️ Destructive Operation: This permanently deletes emails
Parameters:
dry_run(boolean, default: false): Preview modemax_count(number, default: 10): Safety limit
{
"tool": "empty_trash",
"arguments": {
"dry_run": true,
"max_count": 100
}
}
trigger_cleanup
Execute manual cleanup using specific policies.
Parameters:
policy_id(string, required): Cleanup policy to executedry_run(boolean, default: false): Preview modemax_emails(number): Processing limitforce(boolean, default: false): Execute even if policy disabled
{
"tool": "trigger_cleanup",
"arguments": {
"policy_id": "old_low_priority_emails",
"dry_run": true,
"max_emails": 500
}
}
get_cleanup_status
Monitor cleanup automation system status.
Parameters: None
Returns: System status, active jobs, and health metrics
{
"tool": "get_cleanup_status"
}
get_system_health
Get comprehensive system health and performance metrics.
Parameters: None
Returns: Performance metrics, storage usage, and system status
{
"tool": "get_system_health"
}
create_cleanup_policy
Create advanced cleanup policies with detailed criteria.
Parameters:
name(string, required): Policy nameenabled(boolean, default: true): Policy statuspriority(number, default: 50): Execution priority (0-100)criteria(object, required): Cleanup conditionsaction(object, required): Action to takesafety(object, required): Safety configurationschedule(object): Optional scheduling
{
"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
Modify existing cleanup policy configuration.
Parameters:
policy_id(string, required): Policy to updateupdates(object, required): Changes to apply
{
"tool": "update_cleanup_policy",
"arguments": {
"policy_id": "policy_123",
"updates": {
"enabled": false,
"safety": { "max_emails_per_run": 50 }
}
}
}
list_cleanup_policies
View all cleanup policies and their configurations.
Parameters:
active_only(boolean, default: false): Show only enabled policies
{
"tool": "list_cleanup_policies",
"arguments": {
"active_only": true
}
}
delete_cleanup_policy
Remove a cleanup policy permanently.
Parameters:
policy_id(string, required): Policy to delete
{
"tool": "delete_cleanup_policy",
"arguments": {
"policy_id": "outdated_policy_456"
}
}
create_cleanup_schedule
Schedule automatic cleanup policy execution.
Parameters:
name(string, required): Schedule nametype(string, required): Schedule type (daily|weekly|monthly|interval|cron)expression(string, required): Schedule expressionpolicy_id(string, required): Policy to scheduleenabled(boolean, default: true): Schedule status
{
"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
Update global cleanup automation settings.
Parameters:
config(object, required): Configuration updates
{
"tool": "update_cleanup_automation_config",
"arguments": {
"config": {
"continuous_cleanup": {
"enabled": true,
"target_emails_per_minute": 10
}
}
}
}
get_cleanup_metrics
Retrieve cleanup system analytics and performance data.
Parameters:
hours(number, default: 24): History window in hours
{
"tool": "get_cleanup_metrics",
"arguments": {
"hours": 168
}
}
get_cleanup_recommendations
Get AI-powered cleanup policy recommendations.
Parameters: None
Returns: Recommended policies based on email analysis
{
"tool": "get_cleanup_recommendations"
}
📊 Statistics & Analytics Tools
get_email_stats
Comprehensive email usage statistics and analytics.
Parameters:
group_by(string): Grouping method (year|category|label|all)year(number): Filter by specific year
Returns: Detailed statistics by categories, years, sizes, and storage
{
"tool": "get_email_stats",
"arguments": {
"group_by": "all"
}
}
⚙️ Job Management Tools
list_jobs
View all background jobs with filtering options.
Parameters:
limit(number, default: 50): Maximum resultsoffset(number, default: 0): Skip first N jobsstatus(string): Filter by status (pending|running|completed|failed)job_type(string): Filter by job type
{
"tool": "list_jobs",
"arguments": {
"status": "running",
"limit": 25
}
}
get_job_status
Get detailed status of a specific background job.
Parameters:
id(string, required): Job ID to query
Returns: Job details, progress, and results
{
"tool": "get_job_status",
"arguments": {
"id": "categorization_job_789"
}
}
cancel_job
Cancel a running background job.
Parameters:
id(string, required): Job ID to cancel
{
"tool": "cancel_job",
"arguments": {
"id": "cleanup_job_101112"
}
}
Example Workflows
Initial Setup
// 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"
}
}
Clean Up Old Emails
// 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"
}
}
Automated Cleanup Setup
// 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"
}
Development
Project Structure
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
Running in Development
npm run watch # Watch mode for TypeScript
npm run dev # Run with tsx (hot reload)
Testing with MCP Inspector
npm run inspector
Testing
The project includes comprehensive test suites to ensure reliability and correctness of all features.
Running Tests
# Run all tests
npm test
# Run with coverage
npm test -- --coverage
# Run specific test suite
npm test -- --testPathPattern=delete
Integration Tests
Delete Email Tests
The delete functionality has extensive integration tests covering all scenarios:
# 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"
For detailed information about delete email testing, see Delete Email Testing Documentation.
Test Structure
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
Writing Tests
- Follow the existing test patterns
- Use descriptive test names
- Mock external dependencies
- Test both success and error cases
- Maintain test coverage above 80%
Security
- OAuth2 tokens are encrypted at rest
- All bulk operations require confirmation
- Audit logging for all operations
- Rate limiting implemented for Gmail API
- Access pattern tracking for security monitoring
Troubleshooting
Authentication Issues
- Ensure credentials.json is in the correct location
- Check that Gmail API is enabled in GCP
- Verify redirect URI matches your configuration
Performance
- First categorization may take time for large mailboxes
- Use pagination for large result sets
- Enable caching in production
License
MIT
Contributing
Contributions are welcome! Please read our contributing guidelines before submitting PRs.
🏗️ Architecture Overview
The Gmail MCP Server follows a modular, layered architecture designed for scalability, maintainability, and extensibility.
Core Architecture
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
Project Structure
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
Key Design Patterns
- 🔧 Modular Architecture: Each component has a single responsibility
- 🏭 Factory Pattern: Tool creation and configuration management
- 📦 Repository Pattern: Data access abstraction
- 🔄 Observer Pattern: Event-driven cleanup automation
- 🛡️ Strategy Pattern: Multiple categorization algorithms
- ⚡ Caching Strategy: Multi-level caching for performance
Data Flow
- Authentication: OAuth2 flow with secure token storage
- Email Fetching: Batch processing with Gmail API rate limiting
- Categorization: Multi-analyzer pipeline with ML-like scoring
- Search: Indexed search with complex filter combinations
- Operations: Safe execution with dry-run and confirmation steps
🔧 Development & Contributing
Development Setup
# 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
Development Workflow
-
🌟 Feature Development
# Create feature branch git checkout -b feature/new-tool-name # Make changes # Add tests # Update documentation # Test thoroughly npm test npm run build -
🧪 Testing Strategy
- Unit Tests: Individual component testing
- Integration Tests: End-to-end workflow testing
- Performance Tests: Load and stress testing
- Manual Testing: MCP Inspector validation
-
📝 Documentation
- Update README.md for new tools
- Add JSDoc comments for public APIs
- Include usage examples
- Update architecture diagrams
Adding New MCP Tools
-
Create Tool Definition
// 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'] } ]; -
Implement Tool Handler
// src/tools/handlers/my-tool.handler.ts export async function handleMyNewTool(args: MyToolArgs): Promise<MyToolResult> { // Implementation } -
Register Tool
// 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); }); } -
Add Tests
// tests/unit/tools/my-tool.test.ts describe('my_new_tool', () => { it('should handle valid input', async () => { // Test implementation }); });
Code Quality Standards
- 🔍 TypeScript: Strict type checking with comprehensive interfaces
- 📏 ESLint: Code style and quality enforcement
- 🎯 Testing: >80% test coverage requirement
- 📚 Documentation: JSDoc for all public APIs
- 🔒 Security: Input validation and sanitization
- ⚡ Performance: Efficient algorithms and caching
Architecture Guidelines
- 🏗️ Separation of Concerns: Each module has a single responsibility
- 🔌 Dependency Injection: Loose coupling between components
- 📈 Scalability: Designed for large email datasets
- 🛡️ Error Handling: Comprehensive error handling and logging
- 🔄 Async Operations: Non-blocking I/O with proper resource cleanup
Contributing Guidelines
-
🎯 Issues & Feature Requests
- Use issue templates
- Provide detailed descriptions
- Include use cases and examples
-
💻 Pull Requests
- Follow PR template
- Include tests and documentation
- Ensure CI passes
- Request reviews
-
📋 Code Review Checklist
- ✅ Tests pass and coverage maintained
- ✅ Documentation updated
- ✅ Type safety maintained
- ✅ Security considerations addressed
- ✅ Performance implications considered
Extension Points
The server is designed for extensibility:
- 🔧 Custom Tools: Add domain-specific tools
- 🧠 Analyzers: Implement custom categorization algorithms
- 📊 Exporters: Add new export formats
- 🔍 Search Providers: Integrate external search engines
- ☁️ Storage Backends: Add cloud storage providers
📚 Example Workflows
🚀 Initial Setup & Email Organization
// 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
}
}
🧹 Advanced Cleanup Workflow
// 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
}
}
🤖 Automated Cleanup Policy Setup
// 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"
}
🔍 Advanced Search & Analysis
// 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
}
}
📊 Analytics & Monitoring
// 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
}
}
🔒 Security & Safety
🛡️ Authentication & Authorization
- OAuth2 Flow: Secure Google OAuth2 implementation
- Token Encryption: All tokens encrypted at rest using AES-256
- Scope Limitation: Minimal required Gmail API scopes
- Token Rotation: Automatic token refresh and rotation
- Session Management: Secure session handling with expiration
🔐 Data Protection
- Local Storage: Encrypted SQLite database for metadata
- No Email Content Storage: Only metadata stored locally
- Audit Logging: Comprehensive operation logging
- Data Isolation: User data completely isolated
- Secure Communication: HTTPS/TLS for all API communications
⚠️ Safety Mechanisms
- Dry Run Mode: All destructive operations support preview mode
- Confirmation Prompts: Multi-step confirmation for bulk operations
- Safety Limits: Configurable maximum deletion/modification limits
- Backup Integration: Automatic backup before major operations
- Rollback Capability: Ability to restore from archives
🚨 Risk Mitigation
- Rate Limiting: Gmail API rate limit compliance
- Error Handling: Comprehensive error recovery
- Validation: Input sanitization and validation
- Monitoring: Real-time operation monitoring
- Alerts: Automatic alerts for critical issues
🔍 Security Best Practices
// 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
}
}
❓ Troubleshooting
🔐 Authentication Issues
Problem: Authentication failed or 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
Problem: Token expired errors
# 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
📧 Email Processing Issues
Problem: 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
Problem: 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
🗑️ Deletion & Cleanup Issues
Problem: Deletion failed or 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
Problem: Archives not restoring
# Solutions:
1. Check archive location exists
2. Verify archive format compatibility
3. Check available storage space
4. Use smaller batch sizes
⚡ Performance Issues
Problem: 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
Problem: 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
📊 Database Issues
Problem: Database locked or 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
🔧 Development Issues
Problem: 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
Problem: 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
📞 Getting Help
- 📝 Documentation: Check
docs/directory for detailed guides - 🐛 Issues: Create detailed issue reports on GitHub
- 💬 Discussions: Join community discussions
- 🔍 Debugging: Enable debug logging:
LOG_LEVEL=debug
🚨 Emergency Procedures
If you accidentally delete important emails:
- Check Gmail Trash folder first
- Use
restore_emailsif archived - Check local database for metadata
- Contact Gmail support for account recovery
If system is unresponsive:
- Cancel all running jobs:
cancel_job - Restart server:
npm start - Check system health:
get_system_health - Clear caches if needed:
rm -rf data/cache/
📄 License
MIT License - see LICENSE file for details.
🤝 Contributing
We welcome contributions! Please see our Contributing Guidelines for details on:
- 🐛 Bug reports and feature requests
- 💻 Code contributions and pull requests
- 📚 Documentation improvements
- 🧪 Testing and quality assurance
- 🌍 Community support and discussions
⭐ Star this project if you find it useful!
To run the test suite efficiently, always set the environment variable NODE_ENV=test before running tests. This enables fast mode, which:
- Skips artificial delays (e.g., between batches)
- Reduces logging output for cleaner and faster test runs
- Uses smaller data sets in most tests for speed (except explicit performance tests)
Example:
NODE_ENV=test npm test
Or with jest directly:
NODE_ENV=test npx jest
CI/CD:
Your CI pipeline should always set NODE_ENV=test to ensure the fastest possible test execution.