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

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

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

If PowerShell blocks activation:

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

Install dependencies

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

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

Environment variables

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:

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

Authentication

Run:

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:

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

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

Expected result:

True

Verify Gmail read access

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

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:

Ctrl + C

to stop the server.

Claude Desktop integration

On Windows, Claude Desktop MCP configuration is stored at:

$env:APPDATA\Claude\claude_desktop_config.json

Example server entry:

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

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:

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

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.

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

Dependency installation

Gmail API enabled

OAuth Desktop app client

Claude Desktop MCP config

MCP server startup

Smoke test success

Claude log launch attempt

OAuth token creation

GitHub repository page

GitHub rendered README

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 file for full details.