CharlesAD/gmail-mcp-server-claude

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

1. 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
   

2. 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).

3. 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
   

4. 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.

5. 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

1. First fetch unread emails and inspect the JSON to find a threadId.
2. 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.”

3. 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.