workos-gmail-mcp-server 2.0.1

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

Gmail MCP Server

A production-ready Model Context Protocol (MCP) server for Gmail operations. Connect any AI agent to Gmail — send emails, search your inbox, manage drafts, organize with labels, reply to threads, and more.

This is an independent, generalized MCP server. It is not tied to any specific project and can be connected to any AI agent that supports MCP (Claude Desktop, Cursor, WorkOS, or custom agents).

Features

• 📨 Send & Reply: Compose emails, reply to threads, with CC support
• 📥 Read Inbox: Fetch emails from any label (INBOX, SENT, STARRED, etc.)
• 🔍 Search: Full Gmail query syntax (from:, subject:, has:attachment, etc.)
• 📝 Drafts: Create, list, and send drafts
• 🏷️ Labels: List, add, and remove labels on messages
• 🧵 Threads: View full conversation threads
• ✅ Read/Unread: Mark messages as read or unread

Installation

Recommended — no pre-install required (uses uv):

# uv manages a temporary isolated environment automatically
uvx --from workos-gmail-mcp-server gmail-mcp-server

Or install permanently with pip:

pip install workos-gmail-mcp-server

Or install from source:

git clone https://github.com/workos/workos-gmail-mcp-server
cd workos-gmail-mcp-server
pip install -e .

Quick Start

export GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_CLIENT_SECRET="GOCSPX-your-secret"
export GOOGLE_REFRESH_TOKEN="1//your-refresh-token"

# Recommended: run via uvx (no install needed)
uvx --from workos-gmail-mcp-server gmail-mcp-server

# Or if installed via pip
gmail-mcp-server

# Or run as a Python module
python -m gmail_mcp_server

Configuration

Environment Variables

Variable	Required	Description
GOOGLE_CLIENT_ID	✅ Yes	OAuth2 Client ID from Google Cloud Console
GOOGLE_CLIENT_SECRET	✅ Yes	OAuth2 Client Secret
GOOGLE_REFRESH_TOKEN	✅ Yes	OAuth2 Refresh Token (generated once, used to auto-refresh access tokens)

Getting Google OAuth2 Credentials

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 scopes: https://www.googleapis.com/auth/gmail.modify, https://www.googleapis.com/auth/gmail.compose

3. Create OAuth2 Credentials

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. Application type: Desktop app
4. Note down the Client ID and Client Secret

4. Generate a Refresh Token

Option A — Using Google OAuth Playground:

1. Go to OAuth 2.0 Playground
2. Click ⚙️ Settings → check Use your own OAuth credentials → enter your Client ID & Secret
3. In Step 1, add scopes: https://www.googleapis.com/auth/gmail.modify and https://www.googleapis.com/auth/gmail.compose
4. Click Authorize APIs → sign in → grant access
5. In Step 2, click Exchange authorization code for tokens
6. Copy the Refresh Token

Option B — Using the included helper script:

python MCP_servers/get_google_token.py \
  --client-id "YOUR_CLIENT_ID" \
  --client-secret "YOUR_CLIENT_SECRET"

Connecting to AI Agents

Note: Use uvx --from workos-gmail-mcp-server gmail-mcp-server in all configs below. The --from flag is needed because the PyPI package name (workos-gmail-mcp-server) differs from the CLI entry point (gmail-mcp-server). You must have uv installed (brew install uv on macOS).

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "uvx",
      "args": ["--from", "workos-gmail-mcp-server", "gmail-mcp-server"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "GOCSPX-your-secret",
        "GOOGLE_REFRESH_TOKEN": "1//your-refresh-token"
      }
    }
  }
}

Alternative — if you have installed via pip install workos-gmail-mcp-server and prefer not to use uvx, use the full absolute path to the binary instead:

{ "command": "/path/to/your/bin/gmail-mcp-server" }

Find the path with: which gmail-mcp-server

Cursor

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "gmail": {
      "command": "uvx",
      "args": ["--from", "workos-gmail-mcp-server", "gmail-mcp-server"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "GOCSPX-your-secret",
        "GOOGLE_REFRESH_TOKEN": "1//your-refresh-token"
      }
    }
  }
}

VS Code (GitHub Copilot / MCP extension)

Edit .vscode/mcp.json in your project:

{
  "servers": {
    "gmail": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "workos-gmail-mcp-server", "gmail-mcp-server"],
      "env": {
        "GOOGLE_CLIENT_ID": "${input:googleClientId}",
        "GOOGLE_CLIENT_SECRET": "${input:googleClientSecret}",
        "GOOGLE_REFRESH_TOKEN": "${input:googleRefreshToken}"
      }
    }
  },
  "inputs": [
    {
      "id": "googleClientId",
      "type": "promptString",
      "description": "Google OAuth2 Client ID"
    },
    {
      "id": "googleClientSecret",
      "type": "promptString",
      "description": "Google OAuth2 Client Secret",
      "password": true
    },
    {
      "id": "googleRefreshToken",
      "type": "promptString",
      "description": "Google OAuth2 Refresh Token",
      "password": true
    }
  ]
}

WorkOS / Custom Agents

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "gmail": {
      "transport": "stdio",
      "command": "uvx",
      "args": ["--from", "workos-gmail-mcp-server", "gmail-mcp-server"],
      "env": {
        "GOOGLE_CLIENT_ID": "${GOOGLE_CLIENT_ID}",
        "GOOGLE_CLIENT_SECRET": "${GOOGLE_CLIENT_SECRET}",
        "GOOGLE_REFRESH_TOKEN": "${GOOGLE_REFRESH_TOKEN}"
      }
    }
  }
}

Available Tools (14)

Messages

Tool	Description
gmail_send_email	Send an email (to, subject, body, optional cc)
gmail_reply_email	Reply to an email by message ID
gmail_read_emails	Read recent emails from a label (with pagination)
gmail_get_email	Get a single email by message ID
gmail_search_emails	Search emails using Gmail query syntax
gmail_mark_read	Mark an email as read
gmail_mark_unread	Mark an email as unread

Drafts

Tool	Description
gmail_create_draft	Create a draft email
gmail_list_drafts	List draft emails
gmail_send_draft	Send an existing draft

Labels

Tool	Description
gmail_list_labels	List all Gmail labels
gmail_add_label	Add a label to a message
gmail_remove_label	Remove a label from a message

Threads

Tool	Description
gmail_get_thread	Get a full email thread

Development

git clone https://github.com/workos/workos-gmail-mcp-server
cd workos-gmail-mcp-server
pip install -e .

# Run tests
pytest

# Run the server locally
GOOGLE_CLIENT_ID=... GOOGLE_CLIENT_SECRET=... GOOGLE_REFRESH_TOKEN=... python -m gmail_mcp_server

Publishing

To PyPI

pip install build twine
rm -rf dist/ build/ src/*.egg-info
python -m build
pip install "packaging>=24.2"   # required for Metadata 2.4 support in twine
twine check dist/*              # validate before uploading
twine upload dist/*

To MCP Registry

mcp-publisher login github
mcp-publisher publish

License

MIT — see LICENSE for details.