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. Full requirements.

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

Related MCP server: Gmail MCP Server

Tech Stack

• Language: Python 3.12

• MCP 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

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

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:

{
  "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.