Gmail MCP Server

An MCP server that integrates with the Gmail API for intelligent email management, including search, categorization, and archiving.

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.

- 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

- 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

- 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

- 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

- 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

- 🚀 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

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

# Start the MCP server npm start # Authenticate with Gmail (run in your MCP client) { "tool": "authenticate" }

# 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

- Go toGoogle Cloud Console
- Create project or select existing
- Enable Gmail API
- Create OAuth2 credentials (Desktop application)
- Downloadcredentials.jsonto project root

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

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

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

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

The Gmail MCP Server provides25+ specialized toolsorganized into logical categories for comprehensive email management. Each tool includes safety features, parameter validation, and detailed error handling.

Initiates OAuth2 authentication flow with Gmail API.

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

List emails with comprehensive filtering and pagination.

- 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

{ "tool": "list_emails", "arguments": { "category": "high", "year": 2024, "has_attachments": true, "limit": 25 } }

Retrieve complete email content and metadata.

Returns:Full email object with headers, body, attachments

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

Analyze and categorize emails by importance using AI algorithms.

- year(number, required): Year to categorize
- force_refresh(boolean): Re-analyze already categorized emails

Returns:Categorization job status and statistics

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

Advanced multi-criteria email search with intelligent filtering.

- query(string): Text search query
- category(string): Importance filter (high|medium|low)
- year_range(object): Date range withstartand/orendyear
- size_range(object): Size range withminand/ormaxbytes
- sender(string): Filter by sender email address
- has_attachments(boolean): Attachment presence filter
- archived(boolean): Include archived emails
- limit(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" } }

- name(string, required): Name for saved search
- criteria(object, required): Search criteria to save

{ "tool": "save_search", "arguments": { "name": "Large Recent Emails", "criteria": { "size_range": { "min": 5242880 }, "year_range": { "start": 2024 } } } }

Returns:Array of saved searches with usage statistics

{ "tool": "list_saved_searches" }

Archive emails using multiple methods and formats.

- 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

{ "tool": "archive_emails", "arguments": { "category": "low", "older_than_days": 180, "method": "export", "export_format": "mbox", "dry_run": false } }

- 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

{ "tool": "restore_emails", "arguments": { "archive_id": "archive_2023_low_priority", "restore_labels": ["restored", "reviewed"] } }

Create automated archiving rules with scheduling.

- 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)

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

View all configured archive rules and their status.

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

{ "tool": "list_archive_rules", "arguments": { "active_only": true } }

Export emails to external formats with cloud upload support.

- 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

{ "tool": "export_emails", "arguments": { "format": "json", "search_criteria": { "year": 2023 }, "include_attachments": true, "cloud_upload": { "provider": "gdrive", "path": "/backups/gmail-2023" } } }

Safely delete emails with comprehensive safety checks.

⚠️Safety Note:Always usedry_run: truefirst to preview deletions

- 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

{ "tool": "delete_emails", "arguments": { "category": "low", "year": 2022, "dry_run": true, "max_count": 50 } }

Permanently delete all emails in Gmail trash folder.

⚠️Destructive Operation:This permanently deletes emails

- dry_run(boolean, default: false): Preview mode
- max_count(number, default: 10): Safety limit

{ "tool": "empty_trash", "arguments": { "dry_run": true, "max_count": 100 } }

Execute manual cleanup using specific policies.

- 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

{ "tool": "trigger_cleanup", "arguments": { "policy_id": "old_low_priority_emails", "dry_run": true, "max_emails": 500 } }

Monitor cleanup automation system status.

Returns:System status, active jobs, and health metrics

{ "tool": "get_cleanup_status" }

Get comprehensive system health and performance metrics.

Returns:Performance metrics, storage usage, and system status

{ "tool": "get_system_health" }

Create advanced cleanup policies with detailed criteria.

- 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

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

Modify existing cleanup policy configuration.

- policy_id(string, required): Policy to update
- updates(object, required): Changes to apply

{ "tool": "update_cleanup_policy", "arguments": { "policy_id": "policy_123", "updates": { "enabled": false, "safety": { "max_emails_per_run": 50 } } } }

View all cleanup policies and their configurations.