gmail-mcp v1.0.0

Unified Multi-Account Google OAuth2 MCP Server for Gmail. Search, read, compose, send, draft, and organize emails across multiple Google accounts seamlessly.

Features (4 Unified Tools)

• gmail_search: Search emails with official Gmail search syntax (is:unread, from:boss@corp.com, subject:invoice, newer_than:2d, has:attachment)
• gmail_read: Read full email content and metadata (subject, sender, body text, HTML, CC, BCC, labels, attachment list)
• gmail_send: Send emails or create drafts (supports HTML, CC, BCC, thread replies, and file attachments)
• gmail_manage: Labeling, archiving, trash management, read/unread toggles, permanent deletion, and multi-account inventory

Multi-Account Architecture

A single Google Cloud OAuth client (credentials.json) can authenticate multiple Gmail accounts. Tokens are stored per-account in ~/.secrets/gmail/tokens/<account_name>.json.

1. Setup Google OAuth Credentials (One-time)

1. Create a project in Google Cloud Console.
2. Enable the Gmail API.
3. Create an OAuth 2.0 Client ID (Desktop Application).
4. Download the client secret JSON file and save it as ~/.secrets/gmail/credentials.json (or set GMAIL_CREDENTIALS_JSON).

2. Authenticate Accounts

Run the interactive authorization CLI for each account:

gmail-auth default    # Authenticates primary account
gmail-auth work       # Authenticates secondary work account
gmail-auth client_x   # Authenticates any additional account

List all authenticated accounts:

gmail-auth --list

Installation in MCP Clients (Claude Desktop, OpenCode, Cursor, Windsurf)

Option 1: Instant via uvx (Recommended)

{
  "mcpServers": {
    "gmail": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Steph-ux/gmail-mcp.git", "gmail-mcp"]
    }
  }
}

Option 2: Via pip install

pip install git+https://github.com/Steph-ux/gmail-mcp.git

Then in your MCP config:

{
  "mcpServers": {
    "gmail": {
      "command": "gmail-mcp"
    }
  }
}

Option 3: Local Clone (Development)

{
  "mcpServers": {
    "gmail": {
      "command": "python",
      "args": ["D:\\Steph\\script\\gmail-mcp\\server.py"]
    }
  }
}

Usage Examples

1. Search Messages

# Search in default account:
gmail_search(query='is:unread from:github')

# Search in work account:
gmail_search(account='work', query='subject:invoice newer_than:7d')

2. Read Message

gmail_read(account='work', message_id='18f2a9b4c10d')

3. Send Email or Create Draft

# Send direct email:
gmail_send(
    account='default',
    to='colleague@example.com',
    subject='Project Update',
    body_text='Here is the latest status...',
    body_html='<h1>Project Update</h1><p>Here is the latest status...</p>'
)

# Create a draft:
gmail_send(
    account='work',
    to='client@example.com',
    subject='Proposal draft',
    body_text='Please review the proposal.',
    draft=True
)

4. Organize & Manage

# Archive email:
gmail_manage(account='work', action='archive', message_id='18f2a9b4c10d')

# Mark as unread:
gmail_manage(account='default', action='mark_unread', message_id='18f2a9b4c10d')

# Move to trash:
gmail_manage(account='default', action='trash', message_id='18f2a9b4c10d')

# List active accounts:
gmail_manage(action='list_accounts')

Testing

pytest tests

License

MIT