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

  • 🔐 Authentication Tools

  • 📧 Email Management Tools

  • 🔍 Search & Filter Tools

  • 📁 Archive & Export Tools

  • 🗑️ Delete & Cleanup Tools

  • 📊 Statistics & Analytics Tools

  • ⚙️ Job Management Tools

• 🏗️ 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

First Run

📦 Installation

Method 1: Quick Setup (Recommended)

The setup script will guide you through:

• 🔑 Setting up Google Cloud credentials

• 📁 Creating necessary directories

• ⚙️ Configuring environment variables

• 🔧 Initial configuration

Method 2: Manual Setup

1. 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.json to project root

2. Configure environment:

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

3. Create directories:

   mkdir -p data logs archives

4. Install and build:

   npm install npm run build

🔧 Configuration

MCP Client Setup

For Claude Desktop:

For other MCP clients:

Environment Configuration

Key environment variables in .env:

🛠️ 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

📧 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 year

• size_min (number): Minimum size in bytes

• size_max (number): Maximum size in bytes

• archived (boolean): Include archived emails

• has_attachments (boolean): Filter by attachment presence

• labels (array): Filter by Gmail labels

• query (string): Custom Gmail query string

• limit (number, default: 50): Maximum results

• offset (number, default: 0): Skip first N results

get_email_details

Retrieve complete email content and metadata.

Parameters:

• id (string, required): Gmail message ID

Returns: Full email object with headers, body, attachments

categorize_emails

Analyze and categorize emails by importance using AI algorithms.

Parameters:

• year (number, required): Year to categorize

• force_refresh (boolean): Re-analyze already categorized emails

Returns: Categorization job status and statistics

🔍 Search & Filter Tools

search_emails

Advanced multi-criteria email search with intelligent filtering.

Parameters:

• query (string): Text search query

• category (string): Importance filter (high|medium|low)

• year_range (object): Date range with start and/or end year

• size_range (object): Size range with min and/or max bytes

• sender (string): Filter by sender email address

• has_attachments (boolean): Attachment presence filter

• archived (boolean): Include archived emails

• limit (number, default: 50): Maximum results

save_search

Save search criteria for quick reuse.

Parameters:

• name (string, required): Name for saved search

• criteria (object, required): Search criteria to save

list_saved_searches

Retrieve all saved search queries.

Parameters: None

Returns: Array of saved searches with usage statistics

📁 Archive & Export Tools

archive_emails

Archive emails using multiple methods and formats.

Parameters:

• search_criteria (object): Email selection criteria

• category (string): Archive by importance level

• year (number): Archive emails from specific year

• older_than_days (number): Archive emails older than N days

• method (string, required): Archive method (gmail|export)

• export_format (string): Format when exporting (mbox|json)

• export_path (string): Custom export destination

• dry_run (boolean, default: false): Preview mode

restore_emails

Restore emails from previous archives.

Parameters:

• archive_id (string): Specific archive to restore from

• email_ids (array): Individual email IDs to restore

• restore_labels (array): Labels to apply to restored emails

create_archive_rule

Create automated archiving rules with scheduling.

Parameters:

• name (string, required): Descriptive rule name

• criteria (object, required): Archiving conditions

• action (object, required): Archive method and format

• schedule (string): Execution frequency (daily|weekly|monthly)

list_archive_rules

View all configured archive rules and their status.

Parameters:

• active_only (boolean, default: false): Show only enabled rules

export_emails

Export emails to external formats with cloud upload support.

Parameters:

• search_criteria (object): Email selection filters

• format (string, required): Export format (mbox|json|csv)

• include_attachments (boolean, default: false): Include attachments

• output_path (string): Local output path

• cloud_upload (object): Cloud storage configuration

🗑️ 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 filters

• category (string): Delete by importance level

• year (number): Delete from specific year

• size_threshold (number): Delete emails larger than N bytes

• skip_archived (boolean, default: true): Skip archived emails

• dry_run (boolean, default: false): Preview mode

• max_count (number, default: 10): Safety limit

empty_trash

Permanently delete all emails in Gmail trash folder.

⚠️ Destructive Operation: This permanently deletes emails

Parameters:

• dry_run (boolean, default: false): Preview mode

• max_count (number, default: 10): Safety limit

trigger_cleanup

Execute manual cleanup using specific policies.

Parameters:

• policy_id (string, required): Cleanup policy to execute

• dry_run (boolean, default: false): Preview mode

• max_emails (number): Processing limit

• force (boolean, default: false): Execute even if policy disabled

get_cleanup_status

Monitor cleanup automation system status.

Parameters: None

Returns: System status, active jobs, and health metrics

get_system_health

Get comprehensive system health and performance metrics.

Parameters: None

Returns: Performance metrics, storage usage, and system status

create_cleanup_policy

Create advanced cleanup policies with detailed criteria.

Parameters:

• name (string, required): Policy name

• enabled (boolean, default: true): Policy status

• priority (number, default: 50): Execution priority (0-100)

• criteria (object, required): Cleanup conditions

• action (object, required): Action to take

• safety (object, required): Safety configuration

• schedule (object): Optional scheduling

update_cleanup_policy

Modify existing cleanup policy configuration.

Parameters:

• policy_id (string, required): Policy to update

• updates (object, required): Changes to apply

list_cleanup_policies

View all cleanup policies and their configurations.

Parameters:

• active_only (boolean, default: false): Show only enabled policies

delete_cleanup_policy

Remove a cleanup policy permanently.

Parameters:

• policy_id (string, required): Policy to delete

create_cleanup_schedule

Schedule automatic cleanup policy execution.

Parameters:

• name (string, required): Schedule name

• type (string, required): Schedule type (daily|weekly|monthly|interval|cron)

• expression (string, required): Schedule expression

• policy_id (string, required): Policy to schedule

• enabled (boolean, default: true): Schedule status

update_cleanup_automation_config

Update global cleanup automation settings.

Parameters:

• config (object, required): Configuration updates

get_cleanup_metrics

Retrieve cleanup system analytics and performance data.

Parameters:

• hours (number, default: 24): History window in hours

get_cleanup_recommendations

Get AI-powered cleanup policy recommendations.

Parameters: None

Returns: Recommended policies based on email analysis

📊 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

⚙️ Job Management Tools

list_jobs

View all background jobs with filtering options.

Parameters:

• limit (number, default: 50): Maximum results

• offset (number, default: 0): Skip first N jobs

• status (string): Filter by status (pending|running|completed|failed)

• job_type (string): Filter by job type

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

cancel_job

Cancel a running background job.

Parameters:

• id (string, required): Job ID to cancel

Example Workflows

Initial Setup

Clean Up Old Emails

Automated Cleanup Setup

Development

Project Structure

Running in Development

Testing with MCP Inspector

Testing

The project includes comprehensive test suites to ensure reliability and correctness of all features.

Running Tests

Integration Tests

Delete Email Tests

The delete functionality has extensive integration tests covering all scenarios:

For detailed information about delete email testing, see Delete Email Testing Documentation.

Test Structure

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

Project Structure

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

1. Authentication: OAuth2 flow with secure token storage

2. Email Fetching: Batch processing with Gmail API rate limiting

3. Categorization: Multi-analyzer pipeline with ML-like scoring

4. Search: Indexed search with complex filter combinations

5. Operations: Safe execution with dry-run and confirmation steps

🔧 Development & Contributing

Development Setup

Development Workflow

1. 🌟 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

2. 🧪 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

3. 📝 Documentation

   • Update README.md for new tools

   • Add JSDoc comments for public APIs

   • Include usage examples

   • Update architecture diagrams

Adding New MCP Tools

1. 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'] } ];

2. Implement Tool Handler

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

3. 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); }); }

4. 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

1. 🎯 Issues & Feature Requests

   • Use issue templates

   • Provide detailed descriptions

   • Include use cases and examples

2. 💻 Pull Requests

   • Follow PR template

   • Include tests and documentation

   • Ensure CI passes

   • Request reviews

3. 📋 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

🧹 Advanced Cleanup Workflow

🤖 Automated Cleanup Policy Setup

🔍 Advanced Search & Analysis

📊 Analytics & Monitoring

🔒 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

1. Dry Run Mode: All destructive operations support preview mode

2. Confirmation Prompts: Multi-step confirmation for bulk operations

3. Safety Limits: Configurable maximum deletion/modification limits

4. Backup Integration: Automatic backup before major operations

5. 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

❓ Troubleshooting

🔐 Authentication Issues

Problem: Authentication failed or Invalid credentials

Problem: Token expired errors

📧 Email Processing Issues

Problem: Categorization taking too long

Problem: Search results incomplete

🗑️ Deletion & Cleanup Issues

Problem: Deletion failed or Cleanup stuck

Problem: Archives not restoring

⚡ Performance Issues

Problem: Slow search or categorization

Problem: High memory usage

📊 Database Issues

Problem: Database locked or SQLite errors

🔧 Development Issues

Problem: MCP Inspector not working

Problem: TypeScript compilation errors

📞 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:

1. Check Gmail Trash folder first

2. Use restore_emails if archived

3. Check local database for metadata

4. Contact Gmail support for account recovery

If system is unresponsive:

1. Cancel all running jobs: cancel_job

2. Restart server: npm start

3. Check system health: get_system_health

4. 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:

Or with jest directly:

CI/CD:

Your CI pipeline should always set NODE_ENV=test to ensure the fastest possible test execution.