Gmail MCP

Gmail API for AI assistants using Model Context Protocol English | Español | 日本語

---

📋 English Documentation

Pull requests to this repository are welcome.

📖 Table of Contents

• Overview
• Features
• Prerequisites
• Setup
• Usage
• License

🔍 Overview

Gmail MCP is a server implementation that enables AI assistants to interact with Gmail through the MCP (Model Context Protocol). It provides tools for sending emails, managing drafts, reading emails, searching through your inbox, managing Gmail labels and manageing filters.

✨ Features

• ✉️ Send emails and create drafts
• 📬 Read and search emails
• 🗑️ Delete emails
• 🏷️ Manage Gmail labels (create, update, delete)
• 🗂️ Manage Gmail filters (create, update, delete)
• 🔐 OAuth2.0 authentication with Gmail API

📋 Prerequisites

• Python 3.11 or higher
• Gmail account
• Google Cloud Platform project with Gmail API enabled
• uv - Python package installer

🚀 Setup

1. Clone this repository

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

2. Create and activate a virtual environment

uv init

3. Install dependencies

uv pip install -r requirements.txt

4. Set up OAuth credentials

   • Create a directory named credentials in the root of the project
   • Create a project in Google Cloud Console
   • Enable the Gmail API
   • Create OAuth credentials
   • Add the following URI to the Authorized redirect URIs:

     http://localhost:8080/
     

   • Download the credentials JSON file and save it as credentials/client_secret_gmail_oauth.json

5. Add MCP server Please refer to your MCP client’s official documentation for specific instructions. Make sure to adjust the path according to your environment.

{
    "mcpServers": {
        "gmail-mcp": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/your/gmail-mcp/src",
                "run",
                "main.py"
            ]
        }
    }
}

6. Run the server

uv run main.py