Gmail MCP Server

Gmail MCP サーバー

FastMCP（Model Control Protocol）を使用した Gmail 統合で、ツールとプロンプトを通じて AI アシスタントが Gmail を操作できるようにします。

概要

このプロジェクトは、AI アシスタントが次のような Gmail 操作を実行できるサーバー・クライアントアーキテクチャを提供します。

• メールを送信する
• 未読メールを読む
• メールの内容を表示する
• メールをゴミ箱に移動する
• ブラウザーでメールを開く
• メールを既読にする

このシステムでは、認証に Google の OAuth 2.0 を、メール操作に Gmail API を使用します。自然言語のリクエストを理解する LLM 搭載クライアントも含まれるようになりました。

コンポーネント

1. Gmail サーバー（gmail_server.py）

Gmail 操作用の MCP ツールを提供する中核サーバーです。

• FastMCP 統合：FastMCP フレームワークを使用して、Gmail 操作をツールとして公開します
• OAuth 認証：Gmail API の認証、トークン管理、更新を処理します
• メール操作：メールの送信、閲覧、管理機能を実装します
• プロンプト：メールの作成や管理に特化したプロンプトが含まれています

2. スマート Gmail クライアント（test_gmail_server.py）

Gmail サーバーへの自然言語インターフェースです。

• LLM 統合：Google の生成 AI（Gemini）を使用してユーザーのリクエストを解釈します
• 自然言語理解：平易な英語のリクエストをツール呼び出しに変換します
• パラメーター抽出：ユーザーのクエリから必要なパラメーターを自動的に抽出します
• 対話型インターフェース：メール管理のための会話型エクスペリエンスを提供します
• 包括的なログ記録：通信のデバッグに役立つ詳細なログ記録が含まれています

セットアップと要件

前提条件

• Python 3.6+
• Gmail API 認証情報（Gmail 認証用）
• Google Generative AI API キー（LLM 搭載クライアント用）
• requirements.txt に記載されたパッケージ：

  google-auth>=2.22.0
  google-auth-oauthlib>=1.0.0
  google-api-python-client>=2.95.0
  fastmcp>=0.1.0
  typing-extensions>=4.5.0
  google-generativeai>=0.1.0
  python-dotenv>=0.19.0
  

クローン後の初期セットアップ

1. 依存関係をインストールします：

   pip install -r requirements.txt
   

2. Gmail API 認証情報を設定します：

   • Google Cloud Console にアクセスします
   • 新しいプロジェクトを作成するか、既存のプロジェクトを選択します
   • プロジェクトで Gmail API を有効にします
   • OAuth 2.0 認証情報を作成します（クライアントの種類は Desktop）
   • 認証情報の JSON ファイルをダウンロードします
   • ファイル名を credentials.json に変更し、プロジェクトのルートに配置します

3. Gemini API キーを設定します：

   • Google AI Studio にアクセスします
   • 新しい API キーを作成します
   • example.env テンプレートを基に .env ファイルを作成します：

     cp example.env .env
     

   • Gemini API キーを .env ファイルに追加します：

     GOOGLE_API_KEY=your_api_key_here
     

4. 初回実行時にトークンが生成されます：

   • Gmail サーバーを初めて実行すると、ブラウザーウィンドウが開きます
   • Google アカウントにログインし、要求された権限を許可します
   • これにより、今後の認証用に token.json ファイルが生成されます

認証ファイル

このシステムでは、いくつかの認証ファイルが必要です。

• credentials.json：Gmail API 用の Google Cloud Console の OAuth クライアント ID 認証情報
• token.json：Gmail への認証済みアクセス用に生成されるトークンファイル
• .env：Google Generative AI API キーを含む環境変数ファイル

使用方法

Gmail サーバーの起動

Gmail サーバーを起動します：

python gmail_server.py --creds credentials.json --token token.json

サーバーは次のツールを公開します。

• send_email：宛先、件名、本文を指定してメールを送信します
• get_unread_emails：未読メッセージを取得します
• read_email：指定したメールの内容を取得します
• trash_email：メールをゴミ箱に移動します
• open_email：ブラウザーでメールを開きます
• mark_email_as_read：メールを既読にします

スマート Gmail クライアントの使用

スマートクライアントを使うと、自然言語で Gmail を操作できます。

python test_gmail_server.py

コマンドの例：

• 「[recipient] に [topic] についてメールを送信」
• 「未読メールを確認」
• 「最も新しいメッセージを読む」
• 「最新のメールをブラウザーで開く」
• 「[sender] からのメールをゴミ箱に移動」
• 「未読メールを既読にする」

クライアントは次の処理を行います：

1. LLM を使用してリクエストを処理します
2. 実行する Gmail 操作を判断します
3. リクエストから必要なパラメーターを抽出します
4. 不足している情報を確認します
5. 機密性の高い操作を実行する前に確認します
6. 操作を実行し、結果を表示します

実装の詳細

メールコンテンツの処理

• MIME メッセージの解析とデコードに対応します
• マルチパートメッセージと添付ファイルを処理します
• メールヘッダーを適切にデコードします

LLM の統合

• 自然言語理解に Gemini 1.5 Flash を使用します
• LLM の応答を構造化されたツール呼び出しに変換します
• 不正な形式の LLM 応答に対応するフォールバック機構を備えています
• 自由形式のテキストからパラメーターを抽出します

エラー処理

• アプリケーション全体で包括的なログを記録します
• Gmail API からの HTTP エラーを適切に処理します
• LLM の応答が想定した形式でない場合のフォールバック機構を備えています
• クライアントアプリケーション向けに明確なエラー応答を返します

開発

スマートクライアントの拡張

新しい Gmail 操作への対応を追加するには：

1. gmail_server.py に適切なツール実装を追加します
2. スマートクライアントが新しいツールを自動的に検出し、公開します
3. LLM はツールの説明に基づいて、新しい操作に関するリクエストを理解できるようになります

LLM 統合のカスタマイズ

test_gmail_server.py の LLM プロンプトを変更して、次のことができます：

• 特定のユースケースに合わせてパラメーター抽出を改善する
• 特定の種類のリクエストに対する専用の処理を追加する
• Gmail の利用パターンに合わせてシステムを調整する

セキュリティに関する注意

このリポジトリには認証情報ファイルは含まれていません。次のファイルは絶対にコミットしないでください：

• credentials.json ファイル
• token.json ファイル
• API キーを含む .env ファイル

これらのファイルは、機密情報の誤ったコミットを防ぐため、.gitignore ファイルに含まれています。

参考資料

https://medium.com/@jason.summer/create-a-gmail-agent-with-model-context-protocol-mcp-061059c07777