ajaysmb/gmail-mcp

Gmail MCP Server

A Model Context Protocol (MCP) server that gives MCP Clients safe, local access to your Gmail account for reading, searching, and sending mail — with explicit permissions and compact, token-efficient outputs.

Privacy note: The MCP server runs locally on your machine. Gmail data is fetched directly from Google’s APIs to your machine and is only shared with Claude when you explicitly allow a tool call.

Table of Contents

• What You Get
• Prerequisites
• 1) Create a Google Cloud Project
• 2) Enable the Gmail API
• 3) Configure the OAuth Consent Screen
• 4) Create OAuth Client Credentials (Desktop App)
• 5) Get the Code
• 6) Install Python Dependencies
• 7) First Run (Authorize and Create token.json)
• 8) Wire Into Claude Desktop (MCP Config)
• 9) Use It in Claude
• Tool Reference
• Security Tips
• Troubleshooting
• Uninstall / Remove
• License (MIT)

What You Get

• Search & list messages (up to 500 per call) using Gmail’s query syntax (from:, subject:, has:attachment, date ranges, etc.).
• Compact summaries (short-key JSON) to minimize LLM tokens and latency.
• Full message fetch with size limits, optional HTML stripping, and safe defaults.
• Thread summaries (first/last message, unread flag, counts).
• Send email (plain-text) with your explicit approval.
• Caching & batching under the hood to reduce API calls and speed up responses.

Prerequisites

• A Google account with Gmail enabled.
• Python 3.9+ installed.
• An MCP host of your choice. This guide is configured for Claude Desktop (macOS or Windows).

1) Create a Google Cloud Project

1. Open Google Cloud Console and sign in: https://console.cloud.google.com/
2. Create a project: https://console.cloud.google.com/projectcreate Give it any name (e.g., Gmail MCP). Note the selected project in the top bar.

2) Enable the Gmail API

1. While your project is selected, open the Gmail API page: https://console.cloud.google.com/apis/library/gmail.googleapis.com
2. Click Enable.

3) Configure the OAuth Consent Screen

1. Go to the OAuth consent screen: https://console.cloud.google.com/apis/credentials/consent
2. User type: choose External.
3. Set Publishing status to Testing.
4. Under Test users, click Add users and add the Google account(s) that will use this app (typically just your own).
5. Fill in App name, User support email, and Developer contact information. Save.

Using Testing mode with Test users avoids a lengthy app verification process for personal use. The Gmail scopes requested are “sensitive,” which is expected.

4) Create OAuth Client Credentials (Desktop App)

1. Go to Credentials: https://console.cloud.google.com/apis/credentials
2. Click Create credentials → OAuth client ID.
3. Application type: choose Desktop app (recommended for local tools).
4. After it’s created, click Download JSON and save it next to gmail_mcp.py as client_secret.json.

Important: Use Desktop app. “Web application” often causes redirect errors for local tools.

5) Get the Code

# clone this repo (or download ZIP and extract)
git clone https://github.com/yourname/gmail-mcp.git
cd gmail-mcp

Place your downloaded client_secret.json in this folder (the same folder as gmail_mcp.py). The app will create token.json here after your first login.

Do not commit secrets. Add both files to .gitignore:

client_secret.json
token.json

6) Install Python Dependencies

Install Requirements

macOS / Linux

python3 -V
python3 -m venv .venv
source .venv/bin/activate

pip install --upgrade pip
pip install -r requirements.txt

Windows (PowerShell)

py -3 -V
py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
pip install -r requirements.txt

7) First Run (Authorize and Create token.json)

Run the server once to complete Google sign-in and write token.json:

macOS / Linux

source .venv/bin/activate
python3 gmail_mcp.py

Windows (PowerShell)

.\.venv\Scripts\Activate.ps1
python .\gmail_mcp.py

• Your browser opens a Google login/consent page.
• Approve the requested scopes to allow the server to access your Gmail on your behalf.
• After success, token.json is created next to the script. Keep this file safe and private.

If you see a redirect_uri_mismatch error, you likely created a Web application OAuth client instead of a Desktop app. Create a new Desktop app client and download it as client_secret.json.

You can close the terminal after you see a “Starting Gmail MCP (compact mode)… ” log message.

8) Wire Into Claude Desktop (MCP Config)

Claude Desktop reads a JSON config file named claude_desktop_config.json.

Where is the config file?

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

In Claude Desktop you can also open this from Settings → Developer → Edit Config.

Minimal configuration examples

macOS

{
  "mcpServers": {
    "gmail": {
      "command": "python3",
      "args": ["/ABSOLUTE/PATH/TO/gmail_mcp.py"],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

Windows

{
  "mcpServers": {
    "gmail": {
      "command": "python",
      "args": ["C:\\\\ABSOLUTE\\\\PATH\\\\TO\\\\gmail_mcp.py"],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

After saving the config, fully quit and restart Claude Desktop. You should see the MCP hammer icon indicating the server is available.

9) Use It in Claude

Try prompts like:

• “Search my inbox for subject:(invoice) newer_than:30d and summarize the top 20.”
• “Open the full body of message ID ABC123 with strip_html: true.”
• “List threads from from:recruiter@company.com and show unread counts.”
• “Draft an email to alice@example.com about Tuesday’s meeting (do not send yet).”

Claude will ask for your approval before each tool call.

Tool Reference

All outputs are compact JSON (short keys, no extra whitespace) to reduce LLM tokens.

list_messages

List message IDs with an optional Gmail query.

{ "n": "<nextPageToken or ''>", "m": ["18c9...", "18cA..."] }

search_emails

Search and return minimized summaries.

{
  "n": "<nextPageToken>",
  "m": [
    {
      "i": "msgId",
      "t": "threadId",
      "f": "Name <gmail.com>",
      "s": "Subject",
      "d": "2025-08-23T10:01:02+05:30",
      "sn": "Snippet",
      "u": 0,
      "sz": 12345
    }
  ]
}

get_message_summary

One minimized summary by message ID (same shape as above without the list).

get_message_full

Full (still compact). Safe defaults: include_html=false, strip_html=false, max_chars=4096.

{
  "i": "msgId",
  "t": "threadId",
  "h": { "f": "From <domain>", "to": "To...", "s": "Subject", "d": "ISO-8601" },
  "bt": "text body (HTML converted when strip_html=true & no text/plain present)",
  "bh": "html body or '' when include_html=false",
  "sn": "Gmail snippet",
  "sz": 12345
}

list_threads

List thread IDs.

{ "n": "<nextPageToken>", "m": ["threadId1", "threadId2"] }

get_thread_summary

Summary of a thread.

{
  "i": "threadId",
  "c": 5,
  "u": 1,
  "s": "Subject",
  "f": "FirstFrom",
  "lf": "LastFrom",
  "fd": "FirstDate",
  "ld": "LastDate",
  "lsn": "LastSnippet"
}

Security Tips

• Keep client_secret.json and token.json private. Do not commit them to Git.

• To revoke access:

  • Delete token.json and run the server again to re-consent later, or
  • Visit Google account permissions and remove the app: https://myaccount.google.com/permissions

• Scopes requested:

  • https://www.googleapis.com/auth/gmail.readonly
  • https://www.googleapis.com/auth/gmail.send
  • https://www.googleapis.com/auth/gmail.modify

Troubleshooting

Redirect URI mismatch You probably created a Web application OAuth client. Make a Desktop app OAuth client and download it as client_secret.json.

“This app is blocked” or missing scopes Keep the OAuth consent screen in Testing and add your account under Test users.

403 / insufficient permissions Delete token.json and run the server again to re-consent with the latest scopes.

Claude can’t see the server

• Restart Claude Desktop after editing the config.
• Double-check the absolute path and JSON syntax in claude_desktop_config.json.
• On Windows, ensure PYTHONIOENCODING=utf-8 is set as in the example.

Firewall/browser issues during auth Allow the local browser window to open and http://localhost:<random-port> callbacks. Temporarily allow pop-ups if blocked.

Uninstall / Remove

1. Remove the "gmail" block from claude_desktop_config.json and restart Claude Desktop.
2. Delete token.json and optionally client_secret.json.
3. Revoke the app in your Google Account permissions if desired: https://myaccount.google.com/permissions

License (MIT)

Copyright (c) 2025

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the Software or the use or other dealings in the Software.