Gmail MCP

March 16, 2025 · View on GitHub

中文文档

A server for accessing Gmail inbox using the Multimodal Communication Protocol (MCP).

Overview

Gmail MCP is a Python-based server that provides access to your Gmail inbox through the MCP protocol. It allows you to fetch email threads and messages, making it easy to integrate Gmail data into MCP-compatible applications.

Features

  • OAuth2 authentication with Gmail API
  • Fetch recent email threads
  • View detailed message content within threads
  • Support for unread message counts
  • JSON-formatted responses

Prerequisites

  • Python 3.13 or higher
  • A Google Cloud project with Gmail API enabled
  • OAuth 2.0 credentials from Google Cloud Console

Installation

  1. Clone this repository:

    git clone https://github.com/jeasonzhang-eth/gmail-mcp.git
cd gmail-mcp

  2. Create and activate a virtual environment using uv:

    uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

  3. Install dependencies:

    uv sync

Configuration

  1. Create a project in the Google Cloud Console
  2. Enable the Gmail API for your project
  3. Create OAuth 2.0 credentials:
    • Go to "APIs & Services" > "Credentials"
    • Click "Create Credentials" > "OAuth client ID"
    • Select "Desktop application" as the application type
    • Download the JSON file and rename it to credentials.json
    • Place credentials.json in the project root directory

Usage

Starting the Server

Run the server with:

python main.py

The first time you run the server, it will open a browser window for OAuth authentication. After authenticating, the token will be saved for future use.

Testing Gmail Access

To test Gmail access without starting the server:

python main.py --test

This will fetch and display a few recent email threads to verify that everything is working correctly.

Using with MCP Clients

The server exposes the following MCP tool:

  • get_gmail_content(limit: int): Fetches Gmail threads up to the specified limit and returns them as a JSON string containing thread information and messages.

Add to MCP Client

Claude:

{
  "mcpServers": {
    "gmail-mcp": {
      "command": "/Users/xxx/.local/bin/uv", // path to your uv
      "args": [
        "--directory",
        "/path-of-this-project/gmail-mcp", // path of this project
        "run",
        "main.py"      
      ]
    }
  }
}

cursor

/Users/xxx/.local/bin/uv --directory /path-of-this-project/gmail-mcp run main.py

Project Structure

  • main.py: Main server implementation with Gmail API integration
  • setup.sh: Script to install required dependencies
  • pyproject.toml: Project metadata and dependencies
  • .gitignore: Specifies files to be ignored by Git
  • .python-version: Specifies the Python version for the project

License

Apache-2.0 license