# Gmail MCP Server

A Windows-first Python MCP server for Gmail that reads unread emails and creates correctly threaded draft replies using the Gmail API, OAuth 2.0 Desktop credentials, and local stdio transport.

## Overview

This project implements a local Model Context Protocol server for Gmail with Python 3.11 and the official MCP Python SDK using FastMCP.

It exposes two focused tools:

- `get_unread_emails`
- `create_draft_reply`

The server is designed for local Windows development and Claude Desktop-compatible MCP configuration. It is verified locally through Gmail OAuth, direct Python smoke testing, manual stdio server startup, and Claude Desktop configuration pickup through `main.log`.

## What this project demonstrates

- MCP server implementation with Python and FastMCP
- Gmail API integration with OAuth 2.0 Desktop App credentials
- correctly threaded Gmail draft reply creation
- Windows-first local developer workflow
- Claude Desktop local MCP configuration on Windows
- practical verification of a local MCP server independent of hosted execution constraints

The key implementation detail is Gmail threading correctness. Draft replies are created using the original Gmail `threadId`, RFC `Message-ID`, `In-Reply-To`, `References`, and matching subject so that the resulting draft remains attached to the correct conversation.

## Tech stack

- Python 3.11
- MCP Python SDK with FastMCP
- Gmail API
- Google OAuth 2.0 Desktop App credentials
- local stdio MCP transport
- Claude Desktop-compatible Windows configuration

## MCP tools

### `get_unread_emails(limit: int = 10)`

Reads unread Gmail messages from the authenticated mailbox and returns structured message data including:

- `message_id`
- `thread_id`
- `sender`
- `subject`
- `snippet`
- `body_text`
- `internal_date`

### `create_draft_reply(reply_body: str, original_message_id: str | None = None, thread_id: str | None = None)`

Creates a correctly threaded Gmail draft reply.

Accepted inputs:

- `original_message_id`
- `thread_id`

Returned metadata includes:

- `status`
- `draft_id`
- `draft_message_id`
- `thread_id`
- `reply_to`
- `subject`
- `source_message_id`
- `in_reply_to`
- `references`

## Architecture

### Runtime flow

1. The local MCP server exposes Gmail operations as MCP tools.
2. OAuth credentials are loaded from local token storage or refreshed when needed.
3. Gmail API calls are executed on behalf of the authenticated user.
4. The server runs over stdio for local MCP compatibility.
5. Claude Desktop can be configured to launch the server locally on Windows.

### Thread-safe draft creation

To create correctly threaded Gmail draft replies, the implementation uses:

- Gmail `threadId`
- original RFC `Message-ID`
- `In-Reply-To`
- `References`
- matching subject

This avoids creating detached drafts that appear as new conversations instead of replies.

## Project structure

```text
gmail-mcp-server/
├── .env
├── .env.example
├── .gitignore
├── authenticate.py
├── LICENSE
├── README.md
├── requirements.txt
├── run_server.py
├── smoke_test.py
├── pyproject.toml
├── gmail_mcp_server/
│   ├── __init__.py
│   ├── auth.py
│   ├── config.py
│   ├── gmail_client.py
│   └── server.py
├── secrets/
│   ├── credentials.json
│   └── token.json
└── docs/
    └── screenshots/
````

## Local setup

### Prerequisites

* Windows
* Python 3.11
* Git
* Visual Studio Code
* a Gmail account
* a Google Cloud project with Gmail API enabled
* OAuth 2.0 Desktop App credentials
* Claude Desktop for local MCP configuration

### Create and activate the virtual environment

```powershell
Set-Location D:\Projects\gmail-mcp-server
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
```

If PowerShell blocks activation:

```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1
```

### Install dependencies

```powershell
Set-Location D:\Projects\gmail-mcp-server
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt
pip install -e .
```

### Create the runtime environment file

```powershell
Set-Location D:\Projects\gmail-mcp-server
Copy-Item .env.example .env -Force
```

### Environment variables

```env
GOOGLE_CLIENT_SECRET_PATH=D:\Projects\gmail-mcp-server\secrets\credentials.json
GOOGLE_TOKEN_PATH=D:\Projects\gmail-mcp-server\secrets\token.json
GMAIL_USER_ID=me
DEFAULT_UNREAD_LIMIT=10
LOG_LEVEL=INFO
```

## Gmail API configuration

1. Create a Google Cloud project
2. Enable the Gmail API
3. Configure the OAuth consent screen
4. Add these scopes:

   * `https://www.googleapis.com/auth/gmail.readonly`
   * `https://www.googleapis.com/auth/gmail.compose`
5. Create an OAuth client with application type `Desktop app`
6. Save the downloaded client JSON as:

```text
D:\Projects\gmail-mcp-server\secrets\credentials.json
```

## Authentication

Run:

```powershell
Set-Location D:\Projects\gmail-mcp-server
.\.venv\Scripts\Activate.ps1
python .\authenticate.py
```

This opens a browser-based Gmail OAuth flow and saves the token at:

```text
D:\Projects\gmail-mcp-server\secrets\token.json
```

Do not press Ctrl + C during normal browser authentication. Press Ctrl + C only if the process is clearly stuck and no browser window appears.

## Verification

### Verify OAuth token creation

```powershell
Test-Path D:\Projects\gmail-mcp-server\secrets\token.json
```

Expected result:

```powershell
True
```

### Verify Gmail read access

```powershell
Set-Location D:\Projects\gmail-mcp-server
.\.venv\Scripts\Activate.ps1
python .\smoke_test.py
```

Expected result:

* valid JSON output
* unread message count
* structured email objects
* no exception

### Verify MCP server startup

```powershell
Set-Location D:\Projects\gmail-mcp-server
.\.venv\Scripts\Activate.ps1
python .\run_server.py
```

Expected result:

* startup log appears
* no immediate traceback
* the process blocks normally as a stdio server

After confirming startup, press:

```text
Ctrl + C
```

to stop the server.

## Claude Desktop integration

On Windows, Claude Desktop MCP configuration is stored at:

```powershell
$env:APPDATA\Claude\claude_desktop_config.json
```

Example server entry:

```json
{
  "mcpServers": {
    "gmail-mcp-server": {
      "command": "D:\\Projects\\gmail-mcp-server\\.venv\\Scripts\\python.exe",
      "args": [
        "D:\\Projects\\gmail-mcp-server\\run_server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
```

If your existing Claude config already contains a `preferences` block, keep it.

### Verify Claude Desktop config pickup

```powershell
Get-Content "$env:APPDATA\Claude\logs\main.log" -Tail 120
Select-String -Path "$env:APPDATA\Claude\logs\main.log" -Pattern "gmail-mcp-server","Launching MCP Server"
```

Expected evidence includes:

* `MCP Server connection requested for: gmail-mcp-server`
* `Launching MCP Server: gmail-mcp-server`

### Example Claude prompts

These are representative prompts for local MCP usage once the server is configured:

```text
Read my 5 unread emails and summarize the sender, subject, and key message.
```

```text
Create a draft reply to the unread email from John saying: Thanks for the update. I will review this today and respond with next steps.
```

```text
Reply to the latest message in this thread with: Thanks — this looks good to me. Please go ahead.
```

### Verification note

This repository accurately documents:

* local Gmail OAuth success
* Python smoke test success
* manual stdio server startup success
* Claude Desktop configuration presence
* Claude `main.log` launch-attempt evidence

If Claude Desktop cannot execute MCP tools in-chat on a Free plan, that is a client-plan limitation rather than a server implementation failure. For that reason, this README documents Claude Desktop compatibility and local verification without overstating in-chat execution results that were not directly captured.

## Screenshots

### Project structure

![VS Code project structure](docs/screenshots/01-vscode-project-structure.png)

### Dependency installation

![Terminal dependency installation](docs/screenshots/02-terminal-dependency-install.png)

### Gmail API enabled

![Google Cloud Gmail API enabled](docs/screenshots/03-google-cloud-gmail-api-enabled.png)

### OAuth Desktop app client

![Google OAuth client configuration](docs/screenshots/04-google-oauth-client-config.png)

### Claude Desktop MCP config

![Claude Desktop config](docs/screenshots/05-claude-desktop-config.png)

### MCP server startup

![MCP server running locally](docs/screenshots/06-mcp-server-running.png)

### Smoke test success

![Smoke test success](docs/screenshots/07-smoke-test-success.png)

### Claude log launch attempt

![Claude log launch attempt](docs/screenshots/08-claude-log-launch-attempt.png)

### OAuth token creation

![Token file created](docs/screenshots/09-token-json-created.png)

### GitHub repository page

![GitHub repository main page](docs/screenshots/10-github-repo-main-page.png)

### GitHub rendered README

![GitHub rendered README](docs/screenshots/11-github-readme-rendered.png)

## Security notes

* Never commit `.env`
* Never commit `secrets/credentials.json`
* Never commit `secrets/token.json`
* Never publish token contents or credential contents in screenshots
* Redact mailbox-sensitive data before publishing screenshots

## Stretch goal direction

A natural extension is adding external or local reply context to improve draft quality, for example:

* a local style guide
* reusable reply templates
* a lightweight knowledge folder for organization-specific context

This keeps the Gmail integration focused while making generated draft content more useful and more tailored.

## License

This project is licensed under the MIT License.

See the [LICENSE](./LICENSE) file for full details.