workos-gmail-mcp-server 2.0.0

MCP server for Gmail — send, search, read emails, manage drafts and labels via Google OAuth2.

Gmail MCP Server

Production-quality Model Context Protocol server for Gmail.

📧 Send emails — compose and send with CC support 📥 Read emails — fetch from any label (INBOX, SENT, etc.) 🔍 Search emails — full Gmail query syntax 📝 Manage drafts — create and send drafts 🏷️ Organize labels — list, add, remove labels 🧵 View threads — get full conversation threads

Installation

pip install workos-gmail-mcp-server

Or install from source:

cd gmail_mcp_server
pip install -e .

Quick Start

export GOOGLE_CREDENTIALS_PATH=/path/to/credentials.json
export GOOGLE_TOKEN_PATH=/path/to/token.json
gmail-mcp-server

Configuration

Variable	Required	Description
GOOGLE_CREDENTIALS_PATH	✅	Path to OAuth2 credentials.json from Google Cloud Console
GOOGLE_TOKEN_PATH	✅	Path to token.json (generated after first OAuth consent)

OAuth Setup Guide

1. Create a Google Cloud Project

1. Go to Google Cloud Console
2. Create a new project (or select existing)
3. Enable the Gmail API under APIs & Services → Library

2. Configure OAuth Consent Screen

1. Go to APIs & Services → OAuth consent screen
2. Choose External user type
3. Fill in app name and email
4. Add scope: https://www.googleapis.com/auth/gmail.modify

3. Create OAuth2 Credentials

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. Application type: Desktop app
4. Download the JSON file as credentials.json

4. Generate token.json

Run this one-time script to authorize and generate token.json:

from google_auth_oauthlib.flow import InstalledAppFlow

SCOPES = ["https://www.googleapis.com/auth/gmail.modify"]

flow = InstalledAppFlow.from_client_secrets_file("credentials.json", SCOPES)
creds = flow.run_local_server(port=0)

with open("token.json", "w") as f:
    f.write(creds.to_json())

print("token.json created successfully!")

5. Set Environment Variables

export GOOGLE_CREDENTIALS_PATH=/absolute/path/to/credentials.json
export GOOGLE_TOKEN_PATH=/absolute/path/to/token.json

Connecting to AI Agents

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "gmail-mcp-server",
      "env": {
        "GOOGLE_CREDENTIALS_PATH": "/path/to/credentials.json",
        "GOOGLE_TOKEN_PATH": "/path/to/token.json"
      }
    }
  }
}

Cursor / VS Code

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "gmail": {
      "command": "gmail-mcp-server",
      "env": {
        "GOOGLE_CREDENTIALS_PATH": "/path/to/credentials.json",
        "GOOGLE_TOKEN_PATH": "/path/to/token.json"
      }
    }
  }
}

Available Tools

#	Tool	Description
1	gmail_send_email	Send an email (to, subject, body, optional cc)
2	gmail_read_emails	Read recent emails from a label
3	gmail_get_email	Get a single email by message ID
4	gmail_search_emails	Search emails using Gmail query syntax
5	gmail_mark_read	Mark an email as read
6	gmail_mark_unread	Mark an email as unread
7	gmail_create_draft	Create a draft email
8	gmail_send_draft	Send an existing draft
9	gmail_list_labels	List all Gmail labels
10	gmail_add_label	Add a label to a message
11	gmail_remove_label	Remove a label from a message
12	gmail_get_thread	Get a full email thread

Development

# Install in development mode
pip install -e .

# Run tests
pytest tests/ -v

# Run the server
gmail-mcp-server

Project Structure

gmail_mcp_server/
├── pyproject.toml
├── LICENSE
├── README.md
├── server.json
├── src/gmail_mcp_server/
│   ├── __init__.py
│   ├── __main__.py
│   ├── config.py
│   ├── client.py
│   ├── server.py
│   └── tools/
│       ├── __init__.py
│       ├── messages.py
│       ├── drafts.py
│       ├── labels.py
│       └── threads.py
└── tests/
    ├── conftest.py
    ├── test_client.py
    └── test_messages.py

License

MIT