Skip to main content
Glama
deenesjakoruzh
Steph-ux

gmail-mcp

by Steph-ux
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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

Related MCP server: Moist

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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Gmail MCP Server

    cristip73
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables interaction with Gmail through the MCP protocol, supporting sending, reading, searching, replying, forwarding, managing drafts and labels, and saving attachments.
    6 npm
    3
    MIT

  • Moist

    TickTockBent
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables Gmail operations such as reading, sending, searching, and managing emails, threads, labels, and drafts via MCP tools.
    1
    MIT

  • Gmail MCP Connector

    deepthi-vimal
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables reading, searching, sending, and drafting Gmail emails via MCP tools, with support for multiple accounts and background notifications.
    -