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.