gmail-mcp-server

Gmail MCP Server

A comprehensive Model Context Protocol (MCP) server for Gmail integration with SIYA/Claude Desktop and other MCP-compatible clients. Features on-demand authentication, multi-user support, and complete Gmail API access.

📋 Table of Contents

• ✨ Features
• 📦 Quick Start
• 🔧 Gmail API Setup
• 🎯 Authentication Methods
• 🚀 How It Works
• 📧 Available Tools
• 💡 Usage Examples
• 🎯 Common Use Cases
• 👥 Multi-User Mode
• 🛠️ NPX Troubleshooting
• 🔍 Debug & Troubleshooting
• 📋 Command Line Options
• 🔒 Security & Privacy
• 🏗️ Advanced Configuration
• 📚 API Reference

✨ Features

• 🔐 On-Demand Authentication - Only authenticates when you use Gmail tools
• 📧 Complete Gmail Operations - Send, read, search, organize emails
• 📝 Draft Management - Create, edit, and manage email drafts
• 👥 Multi-User Support - Handle multiple Gmail accounts simultaneously
• 🛡️ Secure OAuth2 - Industry-standard Google authentication
• 🔧 Flexible Configuration - Multiple credential methods
• 🚀 Zero-Config Startup - Server starts immediately, authenticates when needed
• 📎 Attachment Support - Handle email attachments with full MIME support
• 🌍 International Support - Full UTF-8 and international character support

📦 Quick Start

For SIYA/Claude Desktop

Add to your siya_desktop_config.json or claude_desktop_config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "gmail-mcp-server@latest",
        "--client-id", "your-google-oauth2-client-id",
        "--client-secret", "your-google-oauth2-client-secret"
      ]
    }
  }
}

Optional: Add custom redirect URI if needed:

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "gmail-mcp-server@latest",
        "--client-id", "your-google-oauth2-client-id",
        "--client-secret", "your-google-oauth2-client-secret",
        "--redirect-uri", "http://localhost:8080/oauth2callback"
      ]
    }
  }
}

⚠️ macOS with NVM Users: If you get "spawn npx ENOENT" error, see NPX Troubleshooting.

Test Installation

npx gmail-mcp-server@latest --help

🔧 Gmail API Setup

1. Enable Gmail API

• Go to Google Cloud Console
• Create or select a project
• Enable the Gmail API
• Go to Credentials → Create Credentials → OAuth 2.0 Client ID
• Choose Desktop Application
• Note your Client ID and Client Secret

2. Configure OAuth2 Redirect

• Default: Add http://localhost:44000/oauth2callback to authorized redirect URIs
• Custom: If using --redirect-uri or GMAIL_REDIRECT_URI, add your custom URI
• Multi-user: Add http://localhost:44000/oauth2callback through http://localhost:44010/oauth2callback

Examples of redirect URIs to add:

http://localhost:44000/oauth2callback  (default)
http://localhost:8080/oauth2callback  (custom port)
https://yourdomain.com/oauth2callback (production)

🎯 Authentication Methods

The server supports three ways to provide credentials:

Method 1: Command Line Arguments (Recommended)

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "gmail-mcp-server@latest",
        "--client-id", "676239218521-example.apps.googleusercontent.com",
        "--client-secret", "GOCSPX-example-secret",
        "--redirect-uri", "http://localhost:8080/oauth2callback"
      ]
    }
  }
}

Note: The --redirect-uri is optional and defaults to http://localhost:44000/oauth2callback.

Method 2: Environment Variables

export GMAIL_CLIENT_ID="your-client-id"
export GMAIL_CLIENT_SECRET="your-client-secret"
export GMAIL_REDIRECT_URI="http://localhost:8080/oauth2callback"  # Optional, defaults to http://localhost:44000/oauth2callback
npx gmail-mcp-server@latest

Method 3: Credentials File

# Download OAuth2 JSON from Google Cloud Console
mkdir -p ~/.gmail-mcp
cp /path/to/credentials.json ~/.gmail-mcp/credentials.json
npx gmail-mcp-server@latest

🔄 Automatic Token Refresh

Once authenticated, you stay signed in for months! The server automatically:

• Refreshes expired access tokens using stored refresh tokens
• Maintains long-term authentication without requiring re-authentication
• Only prompts for new authentication if refresh tokens become invalid

This means you authenticate once and use Gmail tools seamlessly for months without interruption.

🚀 How It Works

On-Demand Authentication

The server starts immediately without requiring authentication upfront:

📧 Gmail MCP Server starting...
🔐 Authentication will be handled when you use Gmail tools or call "quick_authenticate"

When You Use Gmail Tools

First time you try any Gmail operation, you'll see:

🔐 **Authentication Required**

To use Gmail tools, please authenticate first:

**Option 1:** Use the `gmail_authenticate` tool with mode='auto' for automatic authentication
**Option 2:** Use the `gmail_authenticate` tool with mode='manual' to get a clickable authentication link

After authentication, you can use all Gmail tools!

📧 Available Tools

Once authenticated, you have access to:

Email Operations

• gmail_send_email - Send emails with attachments and HTML
• gmail_read_email - Read email content and metadata
• gmail_search_emails - Advanced Gmail search with filters
• gmail_mark_email - Mark as read/unread
• gmail_move_email - Move between folders/labels
• gmail_delete_email - Permanently delete emails
• gmail_get_attachment - Download email attachments

Draft Management

• gmail_draft - Comprehensive draft management with actions: create, list, get, update, delete, send

Authentication & Session

• gmail_authenticate - Authentication with auto/manual modes
• gmail_logout - Sign out and clear credentials

Multi-User Tools (when using --multi-user)

• gmail_authenticate_user - Add new user accounts
• gmail_manage_session - Manage user sessions (info/remove)

💡 Usage Examples

Send an Email

{
  "tool": "gmail_send_email",
  "arguments": {
    "to": ["[e-mail]"],
    "subject": "Hello from SIYA!",
    "text": "This is a plain text email.",
    "html": "<h1>Hello!</h1><p>This is an <strong>HTML</strong> email.</p>"
  }
}

Create a Draft

{
  "tool": "gmail_draft",
  "arguments": {
    "action": "create",
    "to": ["[e-mail]"],
    "subject": "Draft Email",
    "text": "This will be saved as a draft.",
    "attachments": [
      {
        "filename": "document.pdf",
        "content": "base64-encoded-content",
        "contentType": "application/pdf"
      }
    ]
  }
}

Search Emails

{
  "tool": "gmail_search_emails",
  "arguments": {
    "query": "is:unread has:attachment",
    "maxResults": 10
  }
}

List Drafts

{
  "tool": "gmail_draft",
  "arguments": {
    "action": "list",
    "maxResults": 20
  }
}

Update Draft

{
  "tool": "gmail_draft",
  "arguments": {
    "action": "update",
    "draftId": "draft_id_here",
    "to": ["[e-mail]"],
    "subject": "Updated Draft Subject",
    "text": "Updated draft content"
  }
}

Send Draft

{
  "tool": "gmail_draft",
  "arguments": {
    "action": "send",
    "draftId": "draft_id_here"
  }
}

🎯 Common Use Cases

Email Automation

• Newsletter Management - Send bulk emails with personalized content
• Notification Systems - Automated alerts and status updates
• Customer Communication - Automated responses and follow-ups

Content Management

• Draft Workflows - Create, review, and collaborate on email content
• Template Management - Save and reuse email templates as drafts
• Content Scheduling - Prepare emails in advance for later sending

Email Analysis

• Inbox Monitoring - Track unread emails and important messages
• Attachment Processing - Extract and process email attachments
• Search & Filter - Find specific emails based on complex criteria

Multi-Account Management

• Team Collaboration - Manage multiple team member accounts
• Client Communication - Handle emails from different business accounts
• Personal/Business Separation - Organize multiple Gmail accounts

👥 Multi-User Mode

Enable multiple Gmail accounts with the --multi-user flag:

npx gmail-mcp-server@latest --multi-user --client-id "your-id" --client-secret "your-secret"

Multi-User Workflow

• Start server with --multi-user flag
• Add users with gmail_authenticate_user
• Use tools with userId parameter for each operation
• Manage sessions with gmail_manage_session

Multi-User Example

{
  "tool": "gmail_authenticate_user",
  "arguments": {
    "userEmail": "[e-mail]"
  }
}

After authentication, use the returned userId for operations:

{
  "tool": "gmail_send_email",
  "arguments": {
    "userId": "user_12345",
    "to": ["[e-mail]"],
    "subject": "Email from User 1",
    "text": "This email is sent from [e-mail] account"
  }
}

🛠️ NPX Troubleshooting (macOS + NVM)

If you get "spawn npx ENOENT" error on macOS with NVM:

Solution: Create NPX Wrapper

# Create wrapper directory
mkdir -p ~/bin

# Create NPX wrapper script
echo '#!/bin/bash' > ~/bin/npx
echo 'exec ~/.nvm/versions/node/v22.14.0/bin/npx "$@"' >> ~/bin/npx
chmod +x ~/bin/npx

# Update SIYA/Claude Desktop config

Updated SIYA/Claude Desktop Config:

{
  "mcpServers": {
    "gmail": {
      "command": "/Users/yourusername/bin/npx",
      "args": [
        "gmail-mcp-server@latest",
        "--client-id", "your-client-id",
        "--client-secret", "your-client-secret"
      ]
    }
  }
}

Replace /Users/yourusername/ with your actual home directory path.

Find Your Node Version

node --version  # e.g., v22.14.0
ls ~/.nvm/versions/node/  # List available versions

🔍 Debug & Troubleshooting

Enable Debug Mode

npx gmail-mcp-server@latest --debug --client-id "your-id" --client-secret "your-secret"

Common Issues

"Gmail credentials not configured"

• Use npm uninstall -g gmail-mcp-server to clear cache
• Use npx gmail-mcp-server@latest to force latest version

"spawn npx ENOENT"

• Follow NPX Troubleshooting above
• Ensure NPX wrapper has correct Node.js path

"Duplicate tools showing up"

• Update to version 1.0.17+ which fixes duplicate tool issues
• Use npx gmail-mcp-server@latest to get latest version

Authentication popup on startup

• Update to version 1.0.11+ for on-demand authentication
• Use npx gmail-mcp-server@latest to get latest version

Version Check

npx gmail-mcp-server@latest --help  # Shows current version info

📋 Command Line Options

npx gmail-mcp-server@latest [options]

Options:
  --client-id <id>           OAuth2 client ID
  --client-secret <secret>   OAuth2 client secret
  --redirect-uri <uri>       OAuth2 redirect URI (default: http://localhost:44000/oauth2callback)
  --multi-user              Enable multi-user mode
  --setup-auth              Interactive credential setup
  --reset-auth              Clear stored authentication
  --debug                   Enable debug logging
  --non-interactive         Run without prompts
  --help                    Show help information

Examples with Custom Redirect URI

# Custom port
npx gmail-mcp-server@latest --client-id "your-id" --client-secret "your-secret" --redirect-uri "http://localhost:8080/oauth2callback"

# Production domain
npx gmail-mcp-server@latest --client-id "your-id" --client-secret "your-secret" --redirect-uri "https://myapp.com/gmail/callback"

# Environment variable (alternative)
export GMAIL_REDIRECT_URI="http://localhost:3000/auth/callback"
npx gmail-mcp-server@latest --client-id "your-id" --client-secret "your-secret"

🔒 Security & Privacy

• OAuth2 Standard - Uses Google's official authentication
• Local Storage - Tokens stored locally in ~/.gmail-mcp/
• No Data Collection - Your emails stay on Google's servers
• Secure Scopes - Only requests necessary Gmail permissions

🏗️ Advanced Configuration

Custom Redirect URI Configuration

The server supports flexible redirect URI configuration for different deployment scenarios:

Default Configuration:

• Uses http://localhost:44000/oauth2callback
• Automatically starts callback server on port 44000

Custom Port Example:

# Command line
npx gmail-mcp-server@latest --redirect-uri "http://localhost:8080/oauth2callback"

# Environment variable
export GMAIL_REDIRECT_URI="http://localhost:8080/oauth2callback"
npx gmail-mcp-server@latest

Production Deployment:

# For production with custom domain
npx gmail-mcp-server@latest --redirect-uri "https://myapp.com/gmail/callback"

Key Features:

• Auto Port Detection: Server automatically uses the port from your redirect URI
• Custom Paths: Use any callback path (not just /oauth2callback)
• HTTPS Support: Works with production HTTPS domains
• Flexible Configuration: Command line args override environment variables

Custom Token Storage

export GMAIL_TOKEN_DIR="/custom/path/to/tokens"
npx gmail-mcp-server@latest

Non-Interactive Mode

npx gmail-mcp-server@latest --non-interactive --client-id "id" --client-secret "secret"

Reset Authentication

npx gmail-mcp-server@latest --reset-auth

📚 API Reference

Email Operations

• All operations support both single-user and multi-user modes
• Multi-user operations require userId parameter
• Comprehensive error handling and validation
• Support for international characters and attachments

Draft Operations

• Complete draft lifecycle management
• Create, read, update, delete, and send drafts
• Full content preservation including attachments
• Seamless integration with email workflow

Search Capabilities

• Gmail search syntax support (is:unread, has:attachment, etc.)
• Date range filtering (after:2024/01/01, before:2024/12/31)
• Advanced filters (sender, recipient, subject, labels)
• Pagination support for large result sets
• Label-based organization (INBOX, SENT, DRAFT, TRASH, SPAM)

Authentication Features

• On-demand authentication - No upfront auth required
• Automatic token refresh - Seamless credential management
• Multi-account support - Handle multiple Gmail accounts
• Secure token storage - Local encrypted credential storage
• Manual/automatic modes - Flexible authentication options

🤝 Contributing

• Fork the repository
• Create a feature branch
• Make your changes
• Test thoroughly
• Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🆘 Support

• Issues: GitHub Issues
• Documentation: Check README.md and setup guides
• Latest Version: Always use @latest tag for newest features

📧 Happy emailing with SIYA/Claude Desktop! 🚀