Google Drive & Gmail MCP Server

Model Context Protocol server for Google Drive and Gmail APIs with hybrid authentication.

Key Features

• Hybrid Authentication: Service Account (Drive) + OAuth2 (Gmail)
• Automatic Token Management: Prevents 6-month Gmail token expiration
• Complete API Coverage: Full Google Drive and Gmail functionality
• Intelligent Rate Limiting: Automatic Gmail API rate limit management
• Batch Processing: Efficient processing of large Gmail accounts (34K+ messages)
• Smart Analysis: Pre-built analysis tools for common Gmail operations

API Coverage

Google Drive: Files, folders, sharing, search, comments, revisions, account info
Gmail: Messages, sending, search, read/unread, profile, token management

Installation

# Global installation
npm install -g gdrive-mcp-server

# Or run directly with npx (recommended)
npx gdrive-mcp-server

# Or local development
git clone https://github.com/igoralmeida1993/gdrive-mcp.git
cd gdrive-mcp
npm install && npm run build

Setup

1. Google Cloud Console Setup

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Drive API:
   • Go to "APIs & Services" > "Library"
   • Search for "Google Drive API"
   • Click "Enable"

2. Create Credentials

Service Account (for Google Drive):

1. Google Cloud Console > "Credentials" > "Service Account"
2. Download JSON key, extract client_email and private_key

OAuth 2.0 (for Gmail):

1. Google Cloud Console > "Credentials" > "OAuth 2.0 Client IDs"
2. Desktop application type
3. Generate refresh token via OAuth Playground

See HYBRID-AUTH-SETUP.md for detailed steps.

3. Configure Environment

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

Environment Variables (.env file)

# Google Drive & Gmail MCP Server Configuration
# Get these from Google Cloud Console (https://console.cloud.google.com/)

# OAuth 2.0 Credentials (REQUIRED for Gmail functionality)
GOOGLE_CLIENT_ID=your_client_id_here.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your_client_secret_here
GOOGLE_REDIRECT_URI=https://developers.google.com/oauthplayground
GOOGLE_REFRESH_TOKEN=your_refresh_token_here

# Service Account Credentials (REQUIRED for Google Drive functionality)
GOOGLE_SERVICE_ACCOUNT_EMAIL=your-service-account@your-project.iam.gserviceaccount.com
GOOGLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYour private key here\n-----END PRIVATE KEY-----"

# MCP Server Configuration
MCP_SERVER_NAME=gdrive-mcp-server
MCP_SERVER_VERSION=1.0.0

# Optional: Default folder to operate in (leave empty for root)
DEFAULT_FOLDER_ID=

# Optional: File size limits (in bytes)
MAX_FILE_SIZE=104857600  # 100MB default

Usage

Running the Server

# If installed globally
gdrive-mcp-server

# If running from source
npm start

# For development
npm run dev

4. MCP Client Configuration

Claude Desktop configuration:

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["gdrive-mcp-server"],
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id",
        "GOOGLE_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_REFRESH_TOKEN": "your_refresh_token",
        "GOOGLE_SERVICE_ACCOUNT_EMAIL": "[email protected]",
        "GOOGLE_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\nYour private key\n-----END PRIVATE KEY-----"
      }
    }
  }
}

Available Tools

Google Drive: gdrive_list_files, gdrive_get_file, gdrive_download_file, gdrive_upload_file, gdrive_update_file, gdrive_delete_file, gdrive_copy_file, gdrive_move_file, gdrive_create_folder, gdrive_get_folder_info, gdrive_share_file, gdrive_get_permissions, gdrive_remove_permission, gdrive_search, gdrive_get_recent_files, gdrive_get_comments, gdrive_add_comment, gdrive_get_revisions, gdrive_get_about, gdrive_empty_trash

Gmail: gmail_list_messages, gmail_get_message, gmail_send_message, gmail_search_messages, gmail_mark_as_read, gmail_mark_as_unread, gmail_get_profile, gmail_check_token_status, gmail_refresh_token, gmail_batch_process_messages, gmail_smart_analysis

Usage Examples

// List Drive files
{ "tool": "gdrive_list_files", "arguments": { "maxResults": 50 } }

// Upload file
{ "tool": "gdrive_upload_file", "arguments": { "name": "test.txt", "content": "Hello" } }

// Send email
{ "tool": "gmail_send_message", "arguments": { "to": "[email protected]", "subject": "Test", "body": "Hello!" } }

// Search emails
{ "tool": "gmail_search_messages", "arguments": { "query": "is:unread", "maxResults": 10 } }

// Smart analysis for large accounts
{ "tool": "gmail_smart_analysis", "arguments": { "analysisType": "recent", "maxMessages": 500, "daysBack": 7 } }

// Batch process specific messages
{ "tool": "gmail_batch_process_messages", "arguments": { "messageIds": ["id1", "id2"], "batchSize": 20 } }

Security

• Never commit .env files to version control
• Use environment variables in production
• Server automatically refreshes Gmail tokens
• Use minimal required OAuth scopes

Troubleshooting

Common Issues

• "Gmail requires OAuth2": Set OAuth credentials in .env
• "Drive requires Service Account": Set Service Account credentials in .env
• Authentication Error: Verify credentials and enable APIs in Google Cloud Console
• Token Expired: Use gmail_check_token_status and gmail_refresh_token

Help

• HYBRID-AUTH-SETUP.md - Detailed setup guide
• Google Drive API Docs
• Gmail API Docs

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Run tests (if available)
npm test

License

MIT License - see LICENSE file for details

License

MIT