Metadata-Version: 2.4
Name: workos-gmail-mcp-server
Version: 2.0.1
Summary: MCP server for Gmail — send, search, read emails, manage drafts and labels via Google OAuth2.
Author: WorkOS Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/workos/workos-gmail-mcp-server
Project-URL: Repository, https://github.com/workos/workos-gmail-mcp-server
Project-URL: Issues, https://github.com/workos/workos-gmail-mcp-server/issues
Keywords: mcp,gmail,model-context-protocol,ai-tools,email
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Communications :: Email
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: google-auth>=2.0.0
Requires-Dist: google-api-python-client>=2.0.0
Dynamic: license-file

# Gmail MCP Server

<!-- mcp-name: io.github.workos/gmail-mcp-server -->

A production-ready [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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](https://docs.astral.sh/uv/)):**
```bash
# uv manages a temporary isolated environment automatically
uvx --from workos-gmail-mcp-server gmail-mcp-server
```

**Or install permanently with pip:**
```bash
pip install workos-gmail-mcp-server
```

**Or install from source:**
```bash
git clone https://github.com/workos/workos-gmail-mcp-server
cd workos-gmail-mcp-server
pip install -e .
```

## Quick Start

```bash
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](https://console.cloud.google.com/)
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](https://developers.google.com/oauthplayground)
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:**
```bash
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](https://docs.astral.sh/uv/getting-started/installation/) installed (`brew install uv` on macOS).

### Claude Desktop

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

```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:
> ```json
> { "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):

```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"
      }
    }
  }
}
```

### VS Code (GitHub Copilot / MCP extension)

Edit `.vscode/mcp.json` in your project:

```json
{
  "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:

```json
{
  "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

```bash
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
```bash
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
```bash
mcp-publisher login github
mcp-publisher publish
```

## License

MIT — see [LICENSE](LICENSE) for details.
