Gmail MCP Server

Gmail MCP サーバー

Claude Desktop 経由で自然言語によるメール検索を可能にする、Gmail と連携した Java ベースの Model Context Protocol（MCP）サーバーです。このサーバーは、Gmail API と安全な OAuth2 認証を使用して、トピック（例：「プロジェクトの締め切り」）によるメール検索やメール本文の読み取りを行うツールを公開します。

機能

• メールを検索：Gmail の検索構文（例：from:alice budget）を使用して、トピック、送信者、日付でメールを検索します。
• メールを読む：ID を指定して、メールの全文（件名、送信者、本文）を取得します。
• 安全な認証：最小限のアクセス権限として、gmail.readonly スコープを使用する OAuth2 認証を採用しています。
• MCP 連携：JSON-RPC 2.0 を使用し、Stdio 経由で Claude Desktop と通信します。
• 堅牢な設計：本番環境での使用に備え、エラー処理、ログ記録、入力検証を備えています。

前提条件

• Java 17：JDK 17 がインストールされていることを確認してください（java --version）。
• Maven：依存関係の管理に使用します（mvn --version）。
• Google Cloud プロジェクト：Gmail API が有効で、OAuth2 認証情報が設定されていること。
• Claude Desktop：インストール済みで、MCP 用に設定されていること（Anthropic から入手できます）。
• オペレーティングシステム：Windows、macOS、Linux でテスト済みです。

セットアップ手順

1. Google Cloud の認証情報を作成する

1. Google Cloud Console にアクセスします。
2. 新しいプロジェクトを作成します（例：「Gmail MCP Server」）。
3. Gmail API を有効にします：
   • APIs & Services > Library に移動します。
   • 「Gmail API」を検索し、Enable をクリックします。
4. OAuth 2.0 認証情報を作成します：
   • APIs & Services > Credentials > Create Credentials > OAuth 2.0 Client IDs に移動します。
   • アプリケーションの種類として Desktop app を選択します。
   • クライアントに名前を付けます（例：「Gmail MCP Client」）。
   • credentials.json ファイルをダウンロードします。
5. 許可されたリダイレクト URI に http://localhost を追加します：
   • Credentials で OAuth 2.0 Client ID を編集し、Authorized redirect URIs に http://localhost を追加します。

2. プロジェクトをクローンまたはセットアップする

1. リポジトリをクローンします（または新しい Maven プロジェクトを作成します）：

   git clone <repository-url>
   cd gmail-mcp-server
   

   または、新しい Maven プロジェクトを作成し、提供されているファイルをコピーします：
   • src/main/java/com/swiftbeard/gmailmcp/GmailMcpServer.java
   • pom.xml
   • src/main/resources/credentials.json（Google Cloud から取得）
   • src/main/resources/logback.xml
2. credentials.json を src/main/resources/ に配置します。
3. プロジェクトの構成を確認します：

   gmail-mcp-server/
   ├── pom.xml
   ├── src/
   │   ├── main/
   │   │   ├── java/
   │   │   │   └── com/swiftbeard/gmailmcp/
   │   │   │       └── GmailMcpServer.java
   │   │   ├── resources/
   │   │   │   ├── credentials.json
   │   │   │   └── logback.xml
   

3. プロジェクトをビルドする

1. 依存関係をインストールし、プロジェクトをビルドします：

   mvn clean install
   

2. ビルドによって、シェーディング済みの JAR target/gmail-mcp-server-1.0-SNAPSHOT.jar が生成されます。

4. サーバーを実行する

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

   java -jar target/gmail-mcp-server-1.0-SNAPSHOT.jar
   

2. 初回起動時に、サーバーは OAuth2 認証のためにブラウザーを開きます：
   • Gmail アカウントでログインします。
   • アプリによるメールの読み取りを許可します（gmail.readonly スコープを使用します）。
   • 以降の実行で使用するトークンは ~/.gmail-mcp/tokens に保存されます。
3. サーバーは Stdio モードで実行され、Claude Desktop からの MCP リクエストを待ち受けます。

5. Claude Desktop を設定する

1. Anthropic のウェブサイトから Claude Desktop をインストールします。
2. MCP 設定ファイル（例：~/.cursor/mcp.json または Claude の設定ファイル）を探すか、作成します。
3. Gmail MCP サーバーの設定を追加します：

   {
     "mcpServers": {
       "gmail": {
         "command": "java",
         "args": ["-jar", "/full/path/to/gmail-mcp-server-1.0-SNAPSHOT.jar"]
       }
     }
   }
   

   /full/path/to/gmail-mcp-server-1.0-SNAPSHOT.jar を、JAR ファイルの絶対パスに置き換えます（例：/home/user/gmail-mcp-server/target/gmail-mcp-server-1.0-SNAPSHOT.jar）。
4. ファイルを保存し、Claude Desktop を再起動します。

6. 連携をテストする

1. Claude Desktop を開きます。
2. 次のような自然言語のクエリを入力します：

   Find emails about project deadlines from the last 30 days.
   

3. Claude はこれを searchEmails ツール呼び出しに変換します（例：query: "project deadlines after:2025-03-26"）。サーバーはメールの一覧を返します：

   [
     {"id": "abc123", "subject": "Project Deadlines Update", "snippet": "Please review the June 1 deadline..."},
     {"id": "def456", "subject": "Q2 Deadlines", "snippet": "Deadlines for Project X..."}
   ]
   

4. 続けて次のように入力します：

   Read the email with ID abc123.
   

5. サーバーは readEmail("abc123") を実行し、次の結果を返します：

   {
     "id": "abc123",
     "subject": "Project Deadlines Update",
     "from": "[email protected]",
     "body": "Hi team, please review the June 1 deadline for Project X..."
   }
   

6. Claude は結果を自然言語で要約します。

使用例

• トピックで検索：

  Show me emails about budget approvals from last month.
  

  対応する呼び出し：searchEmails("budget approvals after:2025-03-01 before:2025-04-01")。
• 送信者で検索：

  Find emails from [email protected] about conference planning.
  

  対応する呼び出し：searchEmails("from:[email protected] conference planning")。
• 特定のメールを読む：

  Read the email with ID xyz123.
  

  対応する呼び出し：readEmail("xyz123")。

ベストプラクティス

• セキュリティ：
  • アクセスを制限するため、最小限の gmail.readonly スコープを使用します。
  • OAuth2 トークンを ~/.gmail-mcp/tokens に安全に保存します（バージョン管理から除外されています）。
  • インジェクション攻撃を防ぐため、入力を検証します。
• エラー処理：
  • 無効なリクエストや API の障害に対して、JSON-RPC エラーレスポンスを返します。
  • デバッグ用に SLF4J/Logback でエラーを記録します。
• パフォーマンス：
  • Gmail API のレート制限（250 クエリ／分）を考慮し、検索結果を 10 件に制限します。
  • Jackson による効率的な JSON 解析を使用します。
• 保守性：
  • Gmail と MCP のロジックを分離したモジュール構成のコードです。
  • 監視用の包括的なログ記録を行います。

トラブルシューティング

• 認証エラー：
  • credentials.json が src/main/resources/ にあることを確認してください。
  • トークンが無効な場合は、~/.gmail-mcp/tokens を削除して再認証してください。
• サーバーが応答しない：
  • mcp.json 内の JAR パスが正しいことを確認してください。
  • コンソールのログでエラーを確認してください。
• Claude Desktop の問題：
  • Claude Desktop が最新バージョンに更新されていることを確認してください。
  • MCP 設定ファイルの書式が正しいことを確認してください。
• Gmail API のレート制限：
  • レート制限に達した場合は、クエリの頻度を下げるか、指数バックオフを実装してください。

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

• 認証情報：誤ってコミットしないよう、credentials.json と ~/.gmail-mcp/tokens を .gitignore に追加してください。
• OAuth2：トークンを永続化するため、offline アクセスタイプを使用します。不審なアクティビティがないか、Google Cloud Console を確認してください。
• スコープ：不正な操作を防ぐため、gmail.readonly に制限されています。

サーバーの拡張

• ツールの追加：GmailMcpServer.java を拡張し、labelEmail や sendEmail などのツールを追加できます（追加のスコープが必要です）。
• リモートホスティング：クラウドにデプロイする場合（Spring WebFlux など）、SSE または WebSockets を使用するよう変更できます。
• キャッシュ：Caffeine などのインメモリストアを使用して、頻繁に検索されるクエリをキャッシュできます。

コントリビューション

コントリビューションを歓迎します。以下の手順でお願いします。

1. リポジトリをフォークします。
2. フィーチャーブランチを作成します（git checkout -b feature/xyz）。
3. 変更をコミットします（git commit -m "Add XYZ feature"）。
4. ブランチにプッシュします（git push origin feature/xyz）。
5. プルリクエストを作成します。

ライセンス

MIT License です。詳細は LICENSE を参照してください。

謝辞

• Google Gmail API と Anthropic MCP を使用して構築されています。
• GongRzhe の Gmail MCP Server など、コミュニティの MCP サーバーに着想を得ています。

問題や質問がある場合は、GitHub issue を作成するか、メンテナーにお問い合わせください。