Gmail MCP Server Btq

🚀 Gmail MCP サーバ

このプロジェクトは、モデルコンテキストプロトコル (MCP) サーバを実装しており、IMAP と SMTP を通じて Gmail アカウントとのインタラクションを可能にします。メールの検索、内容の取得、ラベルの管理（作成、削除、名前変更、適用、削除）、およびメールの送信/転送を行うツールを提供します。

✨ 主な機能

• メール検索: 日付範囲、キーワード、または元の Gmail クエリ文字列でメールを検索します。特定のフォルダ（受信トレイ、送信済み）内での検索をサポートし、結果の数を制限することができます。Gmail の X-GM-RAW 拡張機能を使用して、効率的な受信トレイ検索（例: category:primary でフィルタリング）を実現します。
• メール内容の取得: シーケンス ID を使用して、特定のメールの完全な内容（ヘッダー情報、本文、添付ファイル）を取得します。
• ラベル管理 (CRUD):
  • すべての利用可能な Gmail ラベル（フォルダ）を一覧表示します。
  • 新しいカスタムラベルを作成します。
  • 既存のラベルの名前を変更します。
  • 既存のカスタムラベルを削除します（システムラベルは削除できません）。
  • 単一のメールにラベルを適用します。
  • 単一のメールからラベルを削除します。
• バッチ操作:
  • シーケンス ID を使用して、複数のメールに一括でラベルを適用します。
  • 複数のメールから一括でラベルを削除します。
  • 複数のメールを特定のラベル/フォルダに移動します。
• メール送信: 新しいメールを送信します（SMTP 設定が必要）。
• メール転送: 既存のメールを転送します（添付ファイルも含む）（SMTP 設定が必要）。
• 毎日のメール数のカウント: 指定された日付範囲内で、毎日受信したメールの数をカウントします。

📚 プロジェクト構成

.
├── .gitignore         # Git が無視するファイルを指定
├── .python-version    # Python バージョンを指定（pyenv 用）
├── LICENSE            # プロジェクトのライセンスファイル
├── pyproject.toml     # Python プロジェクトの設定（依存関係、ビルドシステム）
├── README.md          # このファイル
├── task_list.md       # 開発の進捗状況を追跡
├── uv.lock            # uv パッケージマネージャのロックファイル
├── src/
│   └── email_client/
│       ├── __init__.py
│       ├── config.py        # 環境変数（.env）からの設定の読み込みを処理
│       ├── handlers.py      # MCP ツール呼び出しのロジックを実装
│       ├── imap_client.py   # IMAP サーバとのインタラクション関数を含む
│       ├── server.py        # @modelcontextprotocol/sdk を使用した主な MCP サーバスクリプト
│       ├── smtp_client.py   # SMTP サーバとのインタラクション関数を含む
│       └── tool_definitions.py # すべての利用可能なツールとその詳細な入力モードを定義

🚀 クイックスタート

1. リポジトリをクローンする:

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

2. 仮想環境を作成し、依存関係をインストールする:

   python -m venv .venv
   source .venv/bin/activate  # Windows では .venv\Scripts\activate を使用
   pip install -r requirements.txt
   

3. 環境変数を設定する: .env ファイルを作成し、以下の内容を追加します。

   Gmail_IMAP_HOST=imap.gmail.com
   Gmail_SMTP_HOST=smtp.gmail.com
   Gmail_PORT=143  # IMAP ポート
   Gmail_SSL_PORT=465  # SMTP SSL ポート
   Gmail_EMAIL=your_email@gmail.com
   Gmail_PASSWORD=your_app_specific_password
   

4. サーバを起動する:

   source .venv/bin/activate  # Windows では .venv\Scripts\activate を使用
   python src/email_client/server.py
   

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

• search-emails: メールを検索します。
• get-email-content: 完全なメール詳細を取得します。
• count-daily-emails: 毎日受信したメールの数をカウントします。
• list-labels: すべてのラベル/フォルダを一覧表示します。
• create-label: 新しいラベルを作成します。
• rename-label: 既存のラベルの名前を変更します。
• delete-label: ラベルを削除します。
• apply-label: 単一のメールにラベルを適用します。
• remove-label: 単一のメールからラベルを削除します。
• apply-label-batch: 複数のメールに一括でラベルを適用します。
• remove-label-batch: 複数のメールから一括でラベルを削除します。
• move-email: 単一のメールをラベルに移動します。
• move-email-batch: 複数のメールをラベルに移動します。
• send-email: 新しいメールを送信します。
• forward-email: 既存のメールを転送します。

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