# Gmail MCP Server

A Model Context Protocol (MCP) server that enables Claude to interact with Gmail — read unread emails and create draft replies.

Application project for the [Founders and Coders AI programme](https://www.foundersandcoders.com/). Full [requirements](docs/project-requirements.md).

## Features

- **`get_unread_emails`** — Retrieve unread emails with sender, subject, body, and thread ID
- **`create_draft_reply`** — Draft replies that stay in the right thread
- **`get_reply_context`** — Load a style guide that sneaks Ted Lasso quotes into replies

## Tech Stack

- **Language:** Python 3.12
- **[MCP SDK](https://github.com/modelcontextprotocol/python-sdk):** `mcp` with low-level Server API
- **Gmail API:** `google-api-python-client`, `google-auth-oauthlib`

## Setup

### Prerequisites

- Python 3.10+ (3.12 recommended)
- Claude Desktop app
- Google Cloud project with Gmail API enabled

### 1. Clone and install

```bash
git clone https://github.com/glrta/gmail-mcp-server.git
cd gmail-mcp-server
python3.12 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

### 2. Set up Google Cloud credentials

Follow the detailed guide in [docs/oauth-setup.md](docs/oauth-setup.md) to:

- Create a Google Cloud project
- Enable the Gmail API
- Configure OAuth consent screen
- Download `credentials.json` into the project root

### 3. Authenticate

Run the authentication script once to authorize access to your Gmail:

```bash
python src/authenticate.py
```

This opens your browser for OAuth consent and saves the token to `token.json`.

### 4. Configure Claude Desktop

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

```json
{
  "mcpServers": {
    "gmail-mcp-server": {
      "command": "/FULL/PATH/TO/gmail-mcp-server/venv/bin/python",
      "args": ["/FULL/PATH/TO/gmail-mcp-server/src/server.py"]
    }
  }
}
```

Replace `/FULL/PATH/TO/` with your actual project path.

### 5. Restart Claude Desktop

Completely quit (Cmd+Q) and reopen Claude Desktop.

## Usage

Ask Claude things like:

- "Show me my unread emails"
- "What are my latest 5 unread emails?"
- "Draft a reply to the email from [sender] about [topic] saying [your message]"
- "Reply to thread [thread ID] with: Thanks, I'll look into it."

## Project Structure

```
gmail-mcp-server/
├── src/
│   ├── server.py                 # MCP server — tool definitions and routing
│   ├── gmail_service.py          # Gmail API logic — auth, fetch, draft creation
│   └── authenticate.py           # One-time OAuth script (run before first use)
├── knowledge/
│   └── reply-guide.md            # Reply style guide — tone and templates
├── docs/
│   ├── oauth-setup.md            # Detailed Google Cloud setup guide
│   └── project-requirements.md   # Foundation Project requirements
├── credentials.json              # Google OAuth credentials (git-ignored)
├── token.json                    # Saved auth token (git-ignored)
├── .gitignore
└── README.md
```

## Architecture

```
Claude Desktop
    ↓ (stdio / JSON-RPC)
MCP Server (src/server.py)
    ↓ (asyncio.to_thread)
Gmail Service (src/gmail_service.py)
    ↓ (REST API)
Gmail Account
```

### Design decisions

**File separation — 3 files**
Clean separation: MCP layer, Gmail logic, auth script

**Async handling — `asyncio.to_thread()`**
The MCP server runs an async event loop. The Google Gmail client library is synchronous — it blocks while waiting for API responses. `asyncio.to_thread()` runs those blocking calls in a separate thread so they don't freeze the server.

**Auth approach — Separate script**
The MCP server talks to Claude Desktop over stdout using JSON-RPC. If the OAuth flow ran inside the server, it would print browser prompts to stdout, corrupting the protocol. So auth is a separate script you run once before starting the server.

**Error handling — Return TextContent**
When a tool fails (e.g. Gmail API error), instead of crashing the server, it catches the exception and returns the error as text to Claude. The server stays running so you don't have to restart it.

**Body extraction — Recursive MIME parsing**
Emails aren't plain text — they're nested MIME structures. A message might have a `multipart/mixed` container holding `text/plain` and `text/html` parts, or nested deeper. The `_extract_body` function walks that tree recursively, preferring plain text over HTML.

**Threading — In-Reply-To + References + threadId**
To make a reply appear in the same email thread, Gmail needs three things: the `threadId` (Gmail's internal grouping), `In-Reply-To` (the Message-ID of the email you're replying to), and `References` (the chain of all previous Message-IDs). Missing any of these can break threading in some email clients.

## Troubleshooting

### "token.json not found"

Run `python src/authenticate.py` first.

### Token expired

The server auto-refreshes expired tokens. If it fails, delete `token.json` and run `python src/authenticate.py` again.

### Server not connecting

1. Check logs: `tail -f ~/Library/Logs/Claude/mcp*.log`
2. Verify the Python path in config is correct (must be the venv Python)
3. Ensure all dependencies are installed in the venv

### Tools not appearing / changes not loading

Claude Desktop only reads MCP server config on launch. Any time you add a new tool, change a tool description, or update server code, you need to fully quit (Cmd+Q) and reopen Claude Desktop. A simple window close isn't enough.

## Reflections

It's my first time using Python and I've implemented this project with Claude Code, with only this reflection section being typed by me.
I first focused on understanding the flow with a simple tool to say hello, then moved to Google authentication and gmail tools.
Claude initially suggested using FastMCP, a higher-level wrapper that simplifies server setup. I chose the low-level `mcp.server` API instead so I could better understand how the protocol works under the hood — the explicit tool registration and handler patterns map closely to how I'd build this in TypeScript, which is my day-to-day language at work.

## Demo

Through testing, we found that saying "draft a reply" reliably triggers the tool workflow (including `get_reply_context`), while "write a reply" doesn't — Claude treats it as a general writing task instead. The tool name `create_draft_reply` seems to be what makes "draft" click.

![Demo showing "write" fails but "draft" triggers the tool correctly](docs/demo.png)