Gmail MCP Server

An MCP (Model Context Protocol) server that lets an AI assistant:

Read your unread Gmail messages via the Gmail API
Create properly threaded draft replies in Gmail

Built for the Anthropic programme foundation project as an end-to-end example.

Features

`get_unread_emails(maxResults: int = 10)`

Fetches unread emails from your inbox and returns a JSON structure:

{
  "emails": [
    {
      "id": "string",
      "threadId": "string",
      "from": "string",
      "subject": "string",
      "snippet": "string",
      "internalDate": "string"
    }
  ]
}

Fields:

id – Gmail message ID
threadId – Gmail thread ID (used when replying)
from – sender
subject – email subject
snippet – short preview of the message
internalDate – message timestamp (ms since epoch, as string)

`create_draft_reply(threadId: str, replyBody: str)`

Creates a draft reply in the specified Gmail thread.

Returns a JSON structure:

{
  "draftId": "string | null",
  "threadId": "string",
  "to": "string",
  "subject": "string"
}

Correctly threads the reply using In-Reply-To and References headers.
Leaves the draft in your Gmail Drafts folder for manual review / sending.

OAuth tokens are stored locally in token.json and refreshed automatically.

Architecture / Tech Stack

Language: Python 3
MCP server: mcp Python SDK (FastMCP)
Gmail API client: google-api-python-client, google-auth-oauthlib
Client: Claude Desktop using MCP over stdio

Prerequisites

Python 3.10+ installed
Claude Desktop installed
A Google account with access to Gmail
A Google Cloud project with the Gmail API enabled

Setup

Clone the repository and create a virtual environment

git clone <your-repo-url> gmail-mcp-server
cd gmail-mcp-server

python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\Activate.ps1

pip install -r requirements.txt

Create a Google Cloud project & enable Gmail API
- Go to the Google Cloud Console.
- Create (or select) a project.
- Enable Gmail API for that project.
- Configure the OAuth consent screen (External / Testing is fine for personal use).
Create OAuth credentials
- In APIs & Services → Credentials, create an OAuth client ID.
- Application type: Desktop app.
- Download the JSON file and save it in the project root as:
```
credentials.json
```
First-time Gmail authentication (optional sanity check)

The project includes a small script to verify Gmail is configured correctly:
```
source .venv/bin/activate
python debug_gmail.py
```
This will:
- Open a browser window asking you to sign in and approve Gmail scopes.
- Save a local token.json file for future runs.
- Print the IDs of your unread messages.
Ignore local secrets and environment-specific files

Make sure your .gitignore (in this repo) includes at least:
```
.venv/
__pycache__/
credentials.json
token.json
*.log
```
These files must never be committed to GitHub.

Claude Desktop Configuration

Claude Desktop uses claude_desktop_config.json to know how to launch MCP servers.

On macOS this file is usually at:

~/Library/Application Support/Claude/claude_desktop_config.json

Add (or merge) the following configuration:

{
  "mcpServers": {
    "gmail-mcp-server": {
      "command": "/Users/<you>/Code/gmail-mcp-server/.venv/bin/python",
      "args": [
        "/Users/<you>/Code/gmail-mcp-server/server.py"
      ],
      "env": {
        "GMAIL_CREDENTIALS_PATH": "/Users/<you>/Code/gmail-mcp-server/credentials.json"
      }
    }
  }
}

Replace /Users/<you>/Code/gmail-mcp-server with the actual path to this project on your machine.

After editing the file, quit and restart Claude Desktop so it picks up the new MCP server.

Usage in Claude

Once Claude Desktop is restarted, open a new chat and try:

List and summarise unread emails

“Use the gmail-mcp-server tools to call get_unread_emails with maxResults 5, then summarise the emails.”

Claude will:

Call the get_unread_emails tool.
Receive the JSON list of unread emails.
Summarise them in natural language.

Inspect raw JSON (for debugging / demo)

“Call get_unread_emails with maxResults 3 and show me the raw JSON output.”

Create a draft reply

First fetch unread emails and inspect the JSON to find a threadId.
Then:

“Use the gmail-mcp-server tools to call create_draft_reply with this threadId: <PASTE_THREAD_ID> and a reply body that politely confirms I received their email and proposes a call next week. Tell me what draftId was created.”

Open Gmail → Drafts to see the newly created reply in the correct thread.

Screenshots (for project submission)

Suggested screenshots to include in your submission / repo:

Claude calling get_unread_emails and showing the JSON result.
Claude summarising the unread emails.
Claude calling create_draft_reply and reporting the created draftId.
Gmail UI showing the draft reply in the correct thread.

Place them in a screenshots/ folder and reference them in your application as needed.

Security Notes

This server is intended for local, personal use as a learning/demo project.
credentials.json and token.json are sensitive and must remain local.
Scopes are limited to:
- gmail.readonly – reading messages
- gmail.compose – creating drafts
The server does not send credentials or email content to any third-party service other than Gmail and the local Claude Desktop client.