Metadata-Version: 2.4
Name: workos-gmail-mcp-server
Version: 2.0.0
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

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

# Gmail MCP Server

Production-quality [Model Context Protocol](https://modelcontextprotocol.io/) 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

```bash
pip install workos-gmail-mcp-server
```

Or install from source:

```bash
cd gmail_mcp_server
pip install -e .
```

## Quick Start

```bash
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](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 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`:

```python
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

```bash
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`:

```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:

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

```bash
# 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
