Gmail IMAP MCP Server

Gmail IMAP MCP サーバー

IMAP を使用して Gmail と連携する Model Context Protocol（MCP）サーバーです。このサーバーを使うと、AI アシスタントが Gmail アカウントを操作し、メールの閲覧、検索、管理を行えます。

機能

• Gmail の OAuth2 認証
• Gmail アカウントからメールを読む
• 高度なクエリオプションを使用したメール検索
• 未読メールの表示
• 添付ファイル付きメールの送信
• ラベルの管理（作成、削除、一覧表示）
• ラベル間でのメールの移動
• 添付ファイルのダウンロード
• メールの既読／未読の設定
• 複数の Gmail アカウントに対応
• MCP を介した AI アシスタントとの連携

前提条件

Gmail IMAP MCP サーバーを実行する前に、以下が揃っていることを確認してください。

1. Python 3.12 以降
2. Gmail API が有効になっている Google Cloud プロジェクト
3. OAuth 2.0 クライアント ID の認証情報

インストール

ソースからインストール

1. リポジトリをクローンします：

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

2. 仮想環境を作成して有効化します：

   python -m venv .venv
   # On Windows
   .venv\Scripts\activate
   # On Unix/MacOS
   source .venv/bin/activate
   

3. パッケージをインストールします：

   pip install -e .
   

Google Cloud プロジェクトのセットアップ

1. Google Cloud Console にアクセスします
2. 新しいプロジェクトを作成するか、既存のプロジェクトを選択します
3. プロジェクトで Gmail API を有効にします：
   • 「APIs & Services」>「Library」に移動します
   • 「Gmail API」を検索して有効にします
4. OAuth 2.0 認証情報を作成します：
   • 「APIs & Services」>「Credentials」に移動します
   • 「Create Credentials」>「OAuth client ID」をクリックします
   • アプリケーションの種類として「Desktop app」を選択します
   • クライアント設定ファイルをダウンロードします
5. ダウンロードしたファイルを認証情報ディレクトリに client_secret.json として保存します：

   mkdir -p ~/.gmail_imap_mcp_credentials
   # Move the downloaded file to ~/.gmail_imap_mcp_credentials/client_secret.json
   

アーキテクチャと実装の詳細

認証情報の保存

Gmail IMAP MCP サーバーは、OAuth2 認証情報をユーザーのホームディレクトリ内の ~/.gmail_imap_mcp_credentials/ に保存します。この方法には、次のような利点があります。

1. セキュリティ：アプリケーションディレクトリではなく、ユーザーごとの場所に認証情報を保存します
2. 永続性：認証情報は、異なるセッションやアプリケーションの再起動後も保持されます
3. 互換性：読み取り専用ファイルシステムでの権限の問題を回避します

認証情報ディレクトリには、以下が含まれます。

• client_secret.json：Google Cloud Console で取得した OAuth クライアント認証情報
• 認証済みの各 Gmail アカウントのトークンファイル（形式：token_{email_address}.json）

IMAP の実装

このサーバーは、Gmail での IMAP 操作に Python の imaplib2 ライブラリを使用します。主な実装の詳細は次のとおりです。

1. 接続：ポート 993 で Gmail の IMAP サーバー（imap.gmail.com）に安全に接続します
2. 認証：XOAUTH2 メカニズムを使用して OAuth2 認証を行います
3. メールの取得：RFC822 形式でメールを取得し、Python の email モジュールで解析します
4. ラベル管理：IMAP メールボックス操作を通じて Gmail のラベルを管理します

メール ID の形式

システム内のメール ID は、次の形式に従います。

email://message/{account}_{mailbox}_{id}

各項目の意味は次のとおりです。

• {account}：Gmail アカウントのアドレス
• {mailbox}：メールを含むメールボックス／ラベル
• {id}：メールの一意な IMAP ID

この形式により、異なるアカウントやメールボックスにあるメールをシステム内で一意に識別できます。

使用方法

サーバーの起動

Gmail IMAP MCP サーバーを実行します。

gmail-imap-mcp

Gmail アカウントの認証

1. メールアドレスを指定して authenticate-gmail ツールを使用します
2. ブラウザーで OAuth2 認証フローに従います
3. 認証が完了すると、サーバーは今後の使用に備えて認証情報を保存します

利用可能なツールと使用例

Gmail IMAP MCP サーバーは、Gmail アカウントを操作するための包括的なツールセットを提供します。以下に、利用可能なすべてのツールとその使用例を詳しく説明します。

認証

1. authenticate-gmail

MCP サーバーで使用する Gmail アカウントを認証します。

パラメーター：

• email：認証するメールアドレス

例：

{
  "name": "authenticate-gmail",
  "arguments": {
    "email": "[email protected]"
  }
}

メールの取得と検索

2. search-emails

さまざまな検索条件を使って、Gmail アカウント内のメールを検索します。

パラメーター：

• account：検索対象のメールアカウント
• mailbox：検索対象のメールボックス（デフォルト：INBOX）
• query：検索クエリ
• limit：返すメールの最大数（デフォルト：10）

例 - 特定の送信者からのメールを検索：

{
  "name": "search-emails",
  "arguments": {
    "account": "[email protected]",
    "mailbox": "INBOX",
    "query": "from:[email protected]",
    "limit": 5
  }
}

例 - 特定の件名のメールを検索：

{
  "name": "search-emails",
  "arguments": {
    "account": "[email protected]",
    "query": "subject:\"Meeting Invitation\""
  }
}

例 - 本文に特定のテキストが含まれるメールを検索：

{
  "name": "search-emails",
  "arguments": {
    "account": "[email protected]",
    "query": "TEXT \"project update\""
  }
}

3. get-unread-emails

Gmail アカウントから未読メールを取得します。

パラメーター：

• account：メールの取得元となるメールアカウント
• mailbox：メールの取得元となるメールボックス（デフォルト：INBOX）
• limit：返すメールの最大数（デフォルト：10）

例：

{
  "name": "get-unread-emails",
  "arguments": {
    "account": "[email protected]",
    "limit": 20
  }
}

メールの作成と送信

4. send-email

添付ファイルや HTML コンテンツを任意で含めて、Gmail アカウントからメールを送信します。

パラメーター：

• account：送信元のメールアカウント
• to：宛先のメールアドレス（複数の場合はカンマ区切り）
• subject：メールの件名
• body：プレーンテキスト形式のメール本文
• cc：CC の宛先（任意）
• bcc：BCC の宛先（任意）
• html_body：メール本文の HTML 形式（任意）
• attachments：添付ファイルオブジェクトのリスト（任意）
  • 各添付ファイルオブジェクトには次の項目が必要です：
    • path：ファイルのパス
    • filename：任意のファイル名（任意）
    • content_type：MIME タイプ（任意）

例 - シンプルなメール：

{
  "name": "send-email",
  "arguments": {
    "account": "[email protected]",
    "to": "[email protected]",
    "subject": "Hello from Gmail MCP",
    "body": "This is a test email sent via the Gmail IMAP MCP server."
  }
}

例 - CC、BCC、HTML コンテンツを含むメール：

{
  "name": "send-email",
  "arguments": {
    "account": "[email protected]",
    "to": "[email protected]",
    "subject": "Meeting Agenda",
    "body": "Please find the agenda for our upcoming meeting.",
    "cc": "[email protected]",
    "bcc": "[email protected]",
    "html_body": "<h1>Meeting Agenda</h1><p>Please find the agenda for our <b>upcoming meeting</b>.</p>"
  }
}

例 - 添付ファイル付きのメール：

{
  "name": "send-email",
  "arguments": {
    "account": "[email protected]",
    "to": "[email protected]",
    "subject": "Document Attached",
    "body": "Please find the attached document.",
    "attachments": [
      {
        "path": "/path/to/document.pdf",
        "filename": "important_document.pdf",
        "content_type": "application/pdf"
      }
    ]
  }
}

ラベルの管理

5. create-label

Gmail アカウントに新しいラベル／メールボックスを作成します。

パラメーター：

• account：ラベルの作成先となるメールアカウント
• label_name：作成するラベルの名前

例：

{
  "name": "create-label",
  "arguments": {
    "account": "[email protected]",
    "label_name": "ProjectX"
  }
}

6. delete-label

Gmail アカウントからラベル／メールボックスを削除します。

パラメーター：

• account：ラベルの削除元となるメールアカウント
• label_name：削除するラベルの名前

例：

{
  "name": "delete-label",
  "arguments": {
    "account": "[email protected]",
    "label_name": "OldProject"
  }
}

7. list-labels

Gmail アカウント内のすべてのラベル／メールボックスを一覧表示します。

パラメーター：

• account：ラベルの一覧表示元となるメールアカウント

例：

{
  "name": "list-labels",
  "arguments": {
    "account": "[email protected]"
  }
}

メールの整理

8. move-email

メールをあるラベル／メールボックスから別のラベル／メールボックスに移動します。

パラメーター：

• account：メールアカウント
• email_id：移動するメールの ID（形式：email://message/{account}_{mailbox}_{id}）
• source_mailbox：移動元のメールボックス
• target_mailbox：移動先のメールボックス

例：

{
  "name": "move-email",
  "arguments": {
    "account": "[email protected]",
    "email_id": "email://message/[email protected]_INBOX_12345",
    "source_mailbox": "INBOX",
    "target_mailbox": "ProjectX"
  }
}

添付ファイルの処理

9. download-attachment

メールの添付ファイルをダウンロードします。

パラメーター：

• account：メールアカウント
• email_id：メールの ID（形式：email://message/{account}_{mailbox}_{id}）
• attachment_index：ダウンロードする添付ファイルのインデックス（0 始まり）
• mailbox：メールが含まれるメールボックス（デフォルト：INBOX）
• download_dir：添付ファイルの保存先ディレクトリ（デフォルト："downloads"）

例：

{
  "name": "download-attachment",
  "arguments": {
    "account": "[email protected]",
    "email_id": "email://message/[email protected]_INBOX_12345",
    "attachment_index": 0,
    "download_dir": "my_attachments"
  }
}

メールのステータス管理

10. mark-as-read

メールを既読にします。

パラメーター：

• account：メールアカウント
• email_id：メールの ID（形式：email://message/{account}_{mailbox}_{id}）
• mailbox：メールが含まれるメールボックス（デフォルト：INBOX）

例：

{
  "name": "mark-as-read",
  "arguments": {
    "account": "[email protected]",
    "email_id": "email://message/[email protected]_INBOX_12345"
  }
}

11. mark-as-unread

メールを未読にします。

パラメーター：

• account：メールアカウント
• email_id：メールの ID（形式：email://message/{account}_{mailbox}_{id}）
• mailbox：メールが含まれるメールボックス（デフォルト：INBOX）

例：

{
  "name": "mark-as-unread",
  "arguments": {
    "account": "[email protected]",
    "email_id": "email://message/[email protected]_INBOX_12345"
  }
}

利用可能なプロンプト

サーバーは、AI アシスタントが使用できる次のプロンプトを提供します：

1. summarize-emails

最近のメールの要約を作成します。

パラメーター：

• account：要約対象のメールアカウント
• mailbox：要約対象のメールボックス（デフォルト：INBOX）
• count：要約するメールの数（デフォルト：5）

例：

{
  "name": "summarize-emails",
  "arguments": {
    "account": "[email protected]",
    "mailbox": "INBOX",
    "count": 10
  }
}

AI アシスタントとの連携

Gmail IMAP MCP サーバーは、Model Context Protocol（MCP）に対応した AI アシスタントと連携できます。一般的なワークフローは次のとおりです。

1. 認証：AI アシスタントは authenticate-gmail ツールを使用して、ユーザーの Gmail アカウントを認証します。

2. メール管理：アシスタントは、サーバーが提供するさまざまなツールを使用してメールを取得、検索、管理できます。

3. メールの作成：アシスタントは、ユーザーの指示に基づいてメールの下書き作成や送信を支援できます。

4. メールの整理：アシスタントは、ラベルの作成、ラベル間でのメールの移動、メールの既読・未読の設定によってメールの整理を支援できます。

5. メールの要約：アシスタントは summarize-emails プロンプトを使用してメールを要約できます。

AI アシスタントとの接続

Claude Desktop

Gmail IMAP MCP サーバーを Claude Desktop に接続するには：

1. Gmail IMAP MCP サーバーを起動します：

   python -m gmail_imap_mcp.server
   

2. Claude Desktop を開き、設定（歯車アイコン）に移動します。

3. 「Advanced」セクションまでスクロールし、「Edit MCP Configuration」をクリックします。

4. Gmail IMAP MCP サーバーの設定を追加します：

   {
     "servers": [
       {
         "name": "Gmail IMAP",
         "url": "http://localhost:8080",
         "tools": [
           "list-emails",
           "get-email",
           "search-emails",
           "send-email",
           "list-mailboxes",
           "create-label",
           "move-email",
           "mark-as-read",
           "download-attachment"
         ]
       }
     ]
   }
   

5. 「Save」をクリックし、Claude Desktop を再起動します。

6. 次のように Claude に依頼して、Gmail アカウントを操作できます：

   • 「未読メールを表示して」
   • 「[recipient] に [subject] についてメールを送信して」
   • 「Important という新しいラベルを作成して」
   • 「[sender] からのメールを Important ラベルに移動して」

Windsurf IDE

Gmail IMAP MCP サーバーを Windsurf IDE に接続するには：

1. Gmail IMAP MCP サーバーを起動します：

   python -m gmail_imap_mcp.server
   

2. Windsurf IDE を開き、設定に移動します。

3. 「AI Flow」または「MCP Configuration」セクションを探します。

4. Gmail IMAP MCP サーバーの設定を追加します：

   {
     "servers": [
       {
         "name": "Gmail IMAP",
         "url": "http://localhost:8080",
         "tools": [
           "list-emails",
           "get-email",
           "search-emails",
           "send-email",
           "list-mailboxes",
           "create-label",
           "move-email",
           "mark-as-read",
           "download-attachment"
         ]
       }
     ]
   }
   

5. 設定を保存し、必要に応じて Windsurf を再起動します。

6. Claude Desktop と同じコマンドを使用して、Cascade（Windsurf の AI アシスタント）に Gmail アカウントの操作を依頼できます。

一般的な使用例

1. メールの優先順位付け

Assistant: I'll help you triage your unread emails.
User: Yes, please check my unread emails.
Assistant: [Uses get-unread-emails tool]
Assistant: You have 5 unread emails. The most urgent appears to be from your boss about the quarterly report due tomorrow.
User: Mark that as read and I'll look at it right away.
Assistant: [Uses mark-as-read tool]

2. メールの検索と整理

Assistant: Would you like me to find specific emails for you?
User: Yes, find all emails from [email protected] about the project budget.
Assistant: [Uses search-emails tool with query "from:[email protected] project budget"]
Assistant: I found 3 emails from John about the project budget. Would you like me to create a label for these?
User: Yes, create a "Budget" label and move them there.
Assistant: [Uses create-label tool followed by move-email tool for each email]

3. メールの作成

Assistant: Would you like me to draft an email for you?
User: Yes, write a follow-up email to the marketing team about our campaign results.
Assistant: [Drafts email content]
Assistant: Here's a draft. Would you like me to send it?
User: Yes, but add Sarah in CC.
Assistant: [Uses send-email tool with the drafted content and CC]

Gmail 固有の考慮事項

ラベルの命名規則

Gmail にはラベル名に関する固有の要件があります。

1. ラベル名では大文字と小文字が区別されます。
2. 一部の特殊文字は使用できない場合があります。
3. システムラベル（INBOX、Sent、Trash など）は作成または削除できません。
4. 入れ子のラベルはスラッシュ（例：「Projects/ProjectX」）で表されます。

メール ID の形式

この MCP サーバーで使用されるメール ID の形式は次のとおりです：

email://message/{account}_{mailbox}_{id}

メール ID が必要なツール（mark-as-read や move-email など）を使用する場合は、メール取得ツールから返された完全なリソース URI を使用してください。

セキュリティに関する考慮事項

• サーバーは OAuth2 認証情報をローカルの ~/.gmail_imap_mcp_credentials ディレクトリに保存します。
• client_secret.json やトークンファイルを共有しないでください。
• サーバーは安全な接続を使用して Gmail の IMAP サーバーにのみ接続します。
• メールの添付ファイルは、デフォルトで downloads ディレクトリにダウンロードされます。
• メールデータを保護するため、共有環境でサーバーを使用する際は注意してください。

トラブルシューティング

認証の問題

• client_secret.json が ~/.gmail_imap_mcp_credentials ディレクトリに正しく配置されていることを確認してください。
• Google Cloud プロジェクトで Gmail API が有効になっていることを確認してください。
• トークンの有効期限が切れている場合は、再認証を試してください。
• 「Read-only file system」エラーが表示される場合は、認証情報ディレクトリに書き込み権限があることを確認してください。

接続の問題

• インターネット接続を確認してください。
• Google アカウントに IMAP アクセスを妨げるセキュリティ制限がないことを確認してください。
• Google アカウントの設定で「Less secure app access」を有効にする必要があるか確認してください。

メール送信の問題

• Gmail アカウントで SMTP アクセスが許可されていることを確認してください。
• Google アカウントの設定で「Less secure app access」を有効にする必要があるか確認してください。
• 添付ファイルのサイズが大きすぎないことを確認してください（Gmail の上限は 25MB です）。

ラベル管理に関する問題

• ラベルの作成に失敗する場合は、そのラベルがすでに存在していないか確認してください（大文字と小文字は区別されます）
• システムラベルは作成または削除できません
• ラベル名が Gmail の命名規則に従っていることを確認してください

メールの移動に関する問題

• ラベル間のメールの移動に失敗する場合は、移動元と移動先の両方のラベルが存在することを確認してください
• メール ID の形式が正しいことを確認してください
• メールを変更するための十分な権限があることを確認してください

メール ID の解析に関する問題

• メール ID に対する操作に失敗する場合は、完全なリソース URI を使用していることを確認してください
• システムは URI の最後の部分を実際のメール ID として解析します
• 形式は次のとおりです：email://message/{account}_{mailbox}_{id}

ライセンス

MIT ライセンス

サポート

問題や機能リクエストについては、GitHub リポジトリで issue を作成してください。