home / mcp / gmail mcp server

Gmail MCP Server

Provides an MCP interface to read unread Gmail messages and create threaded draft replies via the Gmail API.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "charlesad-gmail-mcp-server-claude": {
      "command": "/path/to/gmail-mcp-server/.venv/bin/python",
      "args": [
        "/path/to/gmail-mcp-server/server.py"
      ],
      "env": {
        "GMAIL_CREDENTIALS_PATH": "/path/to/gmail-mcp-server/credentials.json"
      }
    }
  }
}

You run an MCP server that reads unread Gmail messages and creates properly threaded draft replies in Gmail. This enables an AI assistant to fetch emails you haven’t read yet, then propose and draft in-context responses you can review and send from Gmail.

How to use

Use a client that supports MCP over stdio to connect to this Gmail MCP Server. You will fetch unread emails, inspect them, and then create draft replies that stay in Gmail for you to review and send.

Typical workflows you can perform:

List unread emails and summarize them in natural language using the get_unread_emails tool with a chosen maxResults value.

Inspect raw JSON output when debugging, then proceed to create a draft reply using the threadId from a selected email.

To create a draft reply, fetch an unread email to obtain its threadId, then call create_draft_reply with that threadId and your reply body. The server will return the draftId and thread details. Open Gmail Drafts to review the draft in the correct thread.

How to install

Prerequisites you need before installation: Python 3.10+,Claude Desktop installed, and a Google account with Gmail access.

Clone the project and set up a virtual environment.

git clone <path-to-repo> 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 and enable Gmail API. Then create OAuth credentials for a Desktop app and download credentials.json. Save it at the project root as credentials.json.

# Place credentials.json into the project root
# The following only verifies Gmail setup once you have credentials
source .venv/bin/activate
python debug_gmail.py

Configure Claude Desktop to launch the MCP server. Update claude_desktop_config.json with the following entry, replacing paths with your actual project paths.

{
  "mcpServers": {
    "gmail_mcp": {
      "command": "/path/to/venv/bin/python",
      "args": [
        "/path/to/gmail-mcp-server/server.py"
      ],
      "env": {
        "GMAIL_CREDENTIALS_PATH": "/path/to/gmail-mcp-server/credentials.json"
      }
    }
  }
}

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

Configuration and security notes

This server runs locally and stores credentials and tokens on your machine. It is intended for personal use and learning.

OAuth scope considerations: read-only access to Gmail messages and the ability to compose drafts.

Environment variables shown in the configuration example must be kept secure and not shared.

Troubleshooting and notes

If you encounter authentication prompts, ensure credentials.json is valid and the Gmail API is enabled for your Google Cloud project.

If drafts do not appear in Gmail, verify the threadId is correct and that the draft was created in the intended Gmail thread.

Available tools

get_unread_emails

Fetch unread emails from your Gmail inbox and return a structured JSON with message metadata including id, threadId, from, subject, snippet, and internalDate.

create_draft_reply

Create a draft reply in a specified Gmail thread, properly threaded with In-Reply-To and References headers, and leave the draft in Gmail Drafts for review.