Gmail MCP

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

💡 Usage

The server can be used with any MCP-compatible client. On first run, it will prompt you to authenticate with your Gmail account.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

📋 日本語ドキュメント

本リポジトリはpullリクエスト大歓迎です。

📖 目次

• 概要
• 機能
• 前提条件
• セットアップ
• 使用方法
• ライセンス

🔍 概要

Gmail MCPは、AIアシスタントがMCP（Model Context Protocol）を通じてGmailを使用できるようにするサーバー実装です。メールの送信、下書きの管理、メールの読み取り、受信トレイの検索、Gmailラベルの管理、フィルタの管理などのツールを提供します。

✨ 機能

• ✉️ メールの送信と下書き作成
• 📬 メールの読み取りと検索
• 🗑️ メールの削除
• 🏷️ Gmailラベルの管理（作成、更新、削除）
• 🗂️ フィルタの管理（作成、更新、削除）
• 🔐 Gmail APIとのOAuth2.0認証 - 📎 添付ファイル送信・下書き（複数可, ローカルファイルパス）

📋 前提条件

• Python 3.11以上
• Gmailアカウント
• Gmail APIが有効化されたGoogle Cloud Platformプロジェクト
• uv - Pythonパッケージインストーラー

🚀 セットアップ

1. リポジトリをクローン

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

2. 仮想環境の作成と有効化

uv init

3. 依存関係のインストール

uv pip install -r requirements.txt

4. OAuth認証情報の設定

   • 最初にプロジェクトのルートディレクトリ直下にcredentialsディレクトリを作成
   • Google Cloud Consoleでプロジェクトを作成
   • Gmail APIを有効化
   • OAuth認証情報を作成
   • 認証済みのリダイレクトURIに以下を追加:

     http://localhost:8080/
     

   • 認証情報JSONファイルをダウンロードし、credentials/client_secret_gmail_oauth.jsonとして保存

5. MCPサーバーを追加 追加方法はご使用のMCPクライアントの公式ドキュメントをご確認ください。 また、パスは環境に合わせて修正してください。

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

6. サーバーの実行

uv run main.py

💡 使用方法

このサーバーは、MCP互換のクライアントと共に使用できます。初回実行時には、Gmailアカウントで認証するよう促されます。

添付ファイルを付けて送信 / 下書き作成

attachments 引数でローカルファイルのパスを指定します（複数可・絶対パス推奨）。

例: 送信

{
  "to": ["[email protected]"],
  "subject": "レポート送付の件",
  "body": "ご確認ください。",
  "attachments": [
    "/Users/you/Documents/report.pdf",
    "/Users/you/Pictures/logo.png"
  ]
}

例: 下書き作成

{
  "to": ["[email protected]"],
  "subject": "資料",
  "body": "添付しています。",
  "attachments": ["/absolute/path/to/file.txt"]
}

注意事項:

• 合計サイズは約24MBを上限とし、それを超える場合はエラーになります（Gmailの25MB制限に対する安全余裕）。
• MIMEタイプは自動推定します。判別できない場合はapplication/octet-streamとして送信します。
• ファイルが存在しない/読み取り不可の場合はエラーになります。

📄 ライセンス

このプロジェクトはMITライセンスの下で提供されています - 詳細はLICENSEファイルをご覧ください。

---

📋 Documentación en Español

Las pull requests a este repositorio son bienvenidas.

📖 Tabla de Contenidos

• Descripción General
• Características
• Requisitos Previos
• Configuración
• Uso
• Licencia

🔍 Descripción General

Gmail MCP es una implementación de servidor que permite a los asistentes de IA interactuar con Gmail a través del MCP (Model Context Protocol). Proporciona herramientas para enviar correos electrónicos, gestionar borradores, leer correos, buscar en tu bandeja de entrada y administrar etiquetas de Gmail.

✨ Características

• ✉️ Enviar correos y crear borradores
• 📬 Leer y buscar correos
• 🗑️ Eliminar correos
• 🏷️ Gestionar etiquetas de Gmail (crear, actualizar, eliminar)
• 🔐 Autenticación OAuth2.0 con la API de Gmail

📋 Requisitos Previos

• Python 3.11 o superior
• Cuenta de Gmail
• Proyecto en Google Cloud Platform con la API de Gmail habilitada
• uv - Instalador de paquetes Python

🚀 Configuración

1. Clonar este repositorio

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

2. Crear y activar un entorno virtual

uv init

3. Instalar dependencias

uv pip install -r requirements.txt

4. Configurar credenciales OAuth

   • Crear un directorio llamado credentials en la raíz del proyecto
   • Crear un proyecto en Google Cloud Console
   • Habilitar la API de Gmail
   • Crear credenciales OAuth
   • Agregar la siguiente URI a las URIs de redirección autorizadas:

     http://localhost:8080/
     

   • Descargar el archivo JSON de credenciales y guardarlo como credentials/client_secret_gmail_oauth.json

5. Agregar servidor MCP Por favor, consulta la documentación oficial de tu cliente MCP para instrucciones específicas. Asegúrate de ajustar la ruta según tu entorno.

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

6. Ejecutar el servidor

uv run main.py

💡 Uso

El servidor puede ser utilizado con cualquier cliente compatible con MCP. En la primera ejecución, te pedirá que te autentiques con tu cuenta de Gmail.

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

---

TODO

• 基本機能実装
• search_emailsで送信メールIDは除外or違う方法で実装