Gmail MCP Server

Gmail MCP サーバー

このプロジェクトでは、IMAP と SMTP 経由で Gmail アカウントとやり取りできる Model Context Protocol（MCP）サーバーを実装しています。メールの検索、内容の取得、ラベルの管理（作成、削除、名前変更、適用、削除）、メールの送信／転送を行うツールを提供します。

機能

• メール検索： 日付範囲、キーワード、または Gmail の生のクエリー文字列でメールを検索します。特定のフォルダー（受信トレイ、送信済み）の検索と、結果数の制限に対応しています。効率的な受信トレイ検索には Gmail の X-GM-RAW 拡張機能を使用します（例：category:primary で絞り込み）。
• メール内容の取得： シーケンス ID を使用して、特定のメールの全内容（ヘッダー、本文、添付ファイル）を取得します。
• ラベル管理（CRUD）：
  • 利用可能な Gmail ラベル（フォルダー）をすべて一覧表示します。
  • カスタムラベルを新規作成します。
  • 既存のカスタムラベルの名前を変更します。
  • 既存のカスタムラベルを削除します（システムラベルは削除できません）。
  • 個々のメールにラベルを適用します。
  • 個々のメールからラベルを削除します。
• 一括操作：
  • シーケンス ID を使用して、複数のメールに同時にラベルを適用します。
  • 複数のメールから同時にラベルを削除します。
  • 複数のメールを特定のラベル／フォルダーに移動します。
• メール送信： 新しいメールを送信します（SMTP の設定が必要です）。
• メール転送： 添付ファイルを含む既存のメールを転送します（SMTP の設定が必要です）。
• 日別メール件数： 指定した日付範囲内で、1 日あたりに受信したメールの件数を数えます。

プロジェクト構成

.
├── .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 を使用します。

   # uv がインストールされていることを確認します（例：pip install uv）
   uv venv  # 仮想環境を作成します（.venv）
   uv sync  # pyproject.toml と uv.lock から依存関係をインストールします
   source .venv/bin/activate # 仮想環境を有効にします
   

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

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

   # .env file
   [email protected]
   GMAIL_PASSWORD=your_app_password # 2FA が有効な場合はアプリ パスワードを使用します
   GMAIL_IMAP_SERVER=imap.gmail.com
   GMAIL_SMTP_SERVER=smtp.gmail.com
   GMAIL_SMTP_PORT=587 # または SSL 用の 465
   

   • 重要： 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：日ごとのメール数をカウントします。
• list-labels：すべてのラベル／フォルダーを一覧表示します。
• create-label：新しいラベルを作成します。
• rename-label：既存のラベルの名前を変更します。
• delete-label：ラベルを削除します。
• apply-label：1 件のメールにラベルを適用します。
• remove-label：1 件のメールからラベルを削除します。
• apply-label-batch：複数のメールにラベルを適用します。
• remove-label-batch：複数のメールからラベルを削除します。
• move-email：1 件のメールをラベルに移動します。
• move-email-batch：複数のメールをラベルに移動します。
• send-email：新しいメールを送信します。
• forward-email：既存のメールを転送します。

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