Gmail MCP サーバー

このプロジェクトは、IMAP と SMTP を介して Gmail アカウントと対話できる Model Context Protocol (MCP) サーバーを実装します。メールの検索、コンテンツの取得、ラベルの管理（作成、削除、名前変更、適用、削除）、メールの送信/転送のためのツールを提供します。

機能

• メール検索: 日付範囲、キーワード、または生の Gmail クエリ文字列でメールを検索します。特定のフォルダー（受信トレイ、送信済み）の検索と結果の制限をサポートします。Gmail の X-GM-RAW 拡張機能を使用して、受信トレイの検索を効率的に行います（例: category:primary によるフィルタリング）。

• メールコンテンツの取得: シーケンス ID を使用して、特定のメールの完全なコンテンツ（ヘッダー、本文、添付ファイル）を取得します。

• ラベル管理 (CRUD):

  • 利用可能なすべての Gmail ラベル（フォルダー）を一覧表示します。

  • 新しいカスタムラベルを作成します。

  • 既存のカスタムラベルの名前を変更します。

  • 既存のカスタムラベルを削除します（システムラベルは削除できません）。

  • 個々のメールにラベルを適用します。

  • 個々のメールからラベルを削除します。

• 一括操作:

  • シーケンス ID を使用して、複数のメールに同時にラベルを適用します。

  • 複数のメールから同時にラベルを削除します。

  • 複数のメールを特定のラベル/フォルダーに移動します。

• メール送信: 新しいメールを送信します（SMTP 設定が必要です）。

• メール転送: 添付ファイルを含む既存のメールを転送します（SMTP 設定が必要です）。

• 1 日あたりのメール数: 指定された日付範囲内で 1 日あたりに受信したメールをカウントします。

Related MCP server: Gmail MCP Server

プロジェクト構造

.
├── .gitignore         # Specifies intentionally untracked files that Git should ignore
├── .python-version    # Specifies Python version (used by pyenv)
├── LICENSE            # Project license file
├── pyproject.toml     # Python project configuration (dependencies, build system)
├── README.md          # This file
├── task_list.md       # Tracks development progress
├── uv.lock            # Lock file for uv package manager
├── src/
│   └── email_client/
│       ├── __init__.py
│       ├── config.py        # Handles loading configuration from environment variables (.env)
│       ├── handlers.py      # Implements the logic for handling MCP tool calls
│       ├── imap_client.py   # Contains functions for interacting with IMAP server
│       ├── server.py        # Main MCP server script using @modelcontextprotocol/sdk
│       ├── smtp_client.py   # Contains functions for interacting with SMTP server
│       ├── tool_definitions.py # Defines the available MCP tools and their schemas
│       └── utils.py         # Utility functions (e.g., email parsing, date formatting)
└── ... (other potential files like test scripts, helper scripts)

セットアップ

1. リポジトリをクローンします（該当する場合）:

   git clone https://github.com/david-strejc/gmail-mcp-server.git
   cd gmail-mcp-server

2. 依存関係をインストールします: このプロジェクトでは、パッケージ管理に uv を使用します。

   # Ensure uv is installed (e.g., pip install uv)
   uv venv  # Create virtual environment (.venv)
   uv sync  # Install dependencies from pyproject.toml and uv.lock
   source .venv/bin/activate # Activate the virtual environment

   （または、uv を使用しない場合は、仮想環境を作成し、requirements.txt が生成されている場合は pip install -r requirements.txt を使用してインストールします）。

3. 環境変数を設定します: プロジェクトのルートディレクトリに .env ファイルを作成し、Gmail の認証情報とサーバー設定を追加します:

   # .env file
   GMAIL_EMAIL=your_email@gmail.com
   GMAIL_PASSWORD=your_app_password # Use an App Password if 2FA is enabled
   GMAIL_IMAP_SERVER=imap.gmail.com
   GMAIL_SMTP_SERVER=smtp.gmail.com
   GMAIL_SMTP_PORT=587 # Or 465 for SSL

   • 重要: Gmail で 2 段階認証プロセスを有効にしている場合は、「アプリ パスワード」を生成して使用する必要があります。標準のパスワードは機能しません。Google のアプリ パスワードに関するドキュメント を参照してください。

   • 2FA を使用していない場合は、「安全性の低いアプリのアクセス」が有効になっていることを確認してください（これは一般的には推奨されません）。

MCP サーバーの実行

仮想環境をアクティブにして、サーバースクリプトを実行します:

source .venv/bin/activate
python src/email_client/server.py

サーバーが起動し、標準入出力を介して MCP リクエストをリッスンします。

MCP クライアント（例: Cline）との統合

MCP クライアントの設定ファイル（例: cline_mcp_settings.json または claude_desktop_config.json）にサーバー設定を追加します。

cline_mcp_settings.json エントリの例:

{
  "mcpServers": {
    "gmail": {
      "command": "/path/to/your/project/gmail-mcp-server/.venv/bin/python",
      "args": ["/path/to/your/project/gmail-mcp-server/src/email_client/server.py"],
      "env": {}, // Environment variables are loaded from .env by the script
      "enabled": true, // Set to true to enable
      "autoApprove": [] // Configure auto-approval if desired
    }
    // ... other servers
  }
}

• /path/to/your/project/gmail-mcp-server を、このプロジェクトディレクトリへの実際の絶対パスに置き換えます。

• command が、プロジェクトの仮想環境内の Python 実行可能ファイル (.venv/bin/python) を指していることを確認します。

設定して有効にすると、クライアントはサーバーに接続し、定義されたツールが利用可能になります。

利用可能なツール（概要）

• search-emails: メールを検索します。

• get-email-content: メールの完全な詳細を取得します。

• count-daily-emails: 1 日あたりのメール数をカウントします。

• list-labels: すべてのラベル/フォルダーを一覧表示します。

• create-label: 新しいラベルを作成します。

• rename-label: 既存のラベルの名前を変更します。

• delete-label: ラベルを削除します。

• apply-label: 1 つのメールにラベルを適用します。

• remove-label: 1 つのメールからラベルを削除します。

• apply-label-batch: 複数のメールにラベルを適用します。

• remove-label-batch: 複数のメールからラベルを削除します。

• move-email: 単一のメールをラベルに移動します。

• move-email-batch: 複数のメールをラベルに移動します。

• send-email: 新しいメールを送信します。

• forward-email: 既存のメールを転送します。

各ツールの詳細な入力スキーマについては、src/email_client/tool_definitions.py を参照してください。