gmail-mcp

gmail-mcp

2
communication

Gmail MCP is a server implementation designed for AI assistants to interact with Gmail using the Model Context Protocol. It includes features such as sending emails, managing drafts, searching inboxes, and managing labels, with authentication via OAuth2.0.

Gmail MCP

Gmail MCP Logo

License Python Version MCP Compatible

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

📋 English Documentation

Pull requests to this repository are welcome.

📖 Table of Contents

🔍 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, and managing Gmail labels.

✨ Features

  • ✉️ Send emails and create drafts
  • 📬 Read and search emails
  • 🗑️ Delete emails
  • 🏷️ Manage Gmail labels (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
  1. Create and activate a virtual environment
uv init
  1. Install dependencies
uv pip install -r requirements.txt

  1. 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

  2. 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"
            ]
        }
    }
}
  1. 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 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
  1. 仮想環境の作成と有効化
uv init
  1. 依存関係のインストール
uv pip install -r requirements.txt

  1. OAuth認証情報の設定

    • 最初にプロジェクトのルートディレクトリ直下にcredentialsディレクトリを作成
    • Google Cloud Consoleでプロジェクトを作成
    • Gmail APIを有効化
    • OAuth認証情報を作成
    • 認証済みのリダイレクトURIに以下を追加: 
      http://localhost:8080/
    • 認証情報JSONファイルをダウンロードし、credentials/client_secret_gmail_oauth.jsonとして保存

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

{
    "mcpServers": {
        "gmail-mcp": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/your/gmail-mcp/src",
                "run",
                "main.py"
            ]
        }
    }
}
  1. サーバーの実行
uv run main.py

💡 使用方法

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

📄 ライセンス

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

TODO

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