Gmail MCP Server

Gmail MCP Server

この MCP サーバーは、Model Context Protocol を通じて Gmail の機能へのアクセスを提供し、Claude などの LLM がメールを操作できるようにします。

機能

• 受信トレイのメールを一覧表示します
• 特定のメールを検索します
• メールの内容を読み取ります
• 新しいメールを送信します
• 既存のメールに返信します
• 個別のメールを削除します
• 複数のメールを一度に一括削除します

セットアップ

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

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt
   

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

   • Google Cloud Console に移動します
   • 新しいプロジェクトを作成します
   • Gmail API を有効にします：
     • サイドバーで「APIs & Services」>「Library」に移動します
     • 「Gmail API」を検索して選択します
     • 「Enable」をクリックします
   • OAuth 2.0 の認証情報を作成します：
     • サイドバーで「APIs & Services」>「Credentials」に移動します
     • 「Create Credentials」をクリックし、「OAuth client ID」を選択します
     • アプリケーションの種類として「Desktop application」を選択します
     • OAuth クライアントの名前を入力します（例：「Gmail MCP Server」）
     • 「Create」をクリックします
     • 認証情報の JSON ファイルをダウンロードし、プロジェクトのルートに credentials.json として保存します

3. サンプルをコピーして .env ファイルを作成します：

   cp .env.example .env
   

4. サーバーを実行します：

   • サーバーを初めて実行すると、認証用のブラウザーウィンドウが開きます
   • 表示される手順に従って、アプリケーションが Gmail アカウントにアクセスすることを許可します

Gmail API の詳細なセットアップ

認証情報ファイルについて

1. credentials.json：

   • このファイルには、Google Cloud から取得した OAuth 2.0 クライアントの認証情報が含まれています
   • Google の OAuth サーバーに対してアプリケーションを識別するために使用されます
   • 形式の例（値はアプリケーションによって異なります）：

     {
       "installed": {
         "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
         "project_id": "your-project-id",
         "auth_uri": "https://accounts.google.com/o/oauth2/auth",
         "token_uri": "https://oauth2.googleapis.com/token",
         "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
         "client_secret": "YOUR_CLIENT_SECRET",
         "redirect_uris": ["http://localhost"]
       }
     }
     

   • 参考として、用意されている credentials.json.example を使用できます

2. token.json：

   • このファイルは初回の認証時に自動的に生成されます
   • Gmail アカウントへのアクセスに必要な OAuth トークンが含まれています
   • ブラウザーで認証フローを完了すると、このファイルが作成されます
   • 形式の例（トークンはアカウントによって異なります）：

     {
       "token": "ya29.a0AfB_byC...",
       "refresh_token": "1//0eXxYz...",
       "token_uri": "https://oauth2.googleapis.com/token",
       "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
       "client_secret": "YOUR_CLIENT_SECRET",
       "scopes": [
         "https://www.googleapis.com/auth/gmail.readonly",
         "https://www.googleapis.com/auth/gmail.send",
         "https://www.googleapis.com/auth/gmail.compose",
         "https://www.googleapis.com/auth/gmail.modify"
       ],
       "expiry": "2025-03-05T14:30:00.000Z"
     }
     

認証フロー

1. サーバーを初めて実行すると：

   • サーバーは token.json ファイルがあるか確認します
   • 見つからない場合、OAuth 2.0 の認証フローが開始されます
   • Google アカウントへのログインを求めるブラウザーウィンドウが開きます
   • アプリケーションへのアクセス許可を求められます
   • 許可すると、ブラウザーに成功メッセージが表示されます
   • サーバーはトークンを token.json に自動的に保存します

2. 2 回目以降の実行では：

   • サーバーは既存の token.json ファイルを使用します
   • トークンの有効期限が切れている場合、自動的に更新されます
   • 更新されたトークンは token.json に再び保存されます

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

• credentials.json と token.json ファイルを安全に保管してください
• これらのファイルをバージョン管理にコミットしないでください
• .gitignore ファイルでは、これらのファイルを除外するよう設定されています
• 認証情報が漏えいした疑いがある場合は、Google Cloud Console で無効化し、新しい認証情報を生成してください

使用方法

サーバーを起動します：

source venv/bin/activate  # On Windows: venv\Scripts\activate
python -m src.server

デフォルトのポート（8000）がすでに使用中の場合、サーバーは利用可能なポートを自動的に探します。.env ファイルで優先するホスト、ポート、パスを設定できます：

SERVER_HOST=0.0.0.0   # The host address to bind to
SERVER_PORT=8000      # The preferred port (will use next available if busy)
SERVER_PATH=/mcp      # The URL path for the MCP server

claude_desktop_config.json にこのサーバーを追加して、Claude Desktop で使用するよう設定します：

{
  "mcpServers": {
    "gmail": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/gmail-mcp-server"
    }
  }
}

利用可能なツール関数

Gmail MCP サーバーでは、次のツール関数を利用できます：

1. list_emails - Gmail の受信トレイからメールを一覧表示します

   • パラメーター：
     • max_results：返すメールの最大数（デフォルト：10）
     • label：絞り込みに使用する Gmail ラベル（デフォルト：INBOX）

2. get_email - 特定のメールの全文を取得します

   • パラメーター：
     • email_id：取得するメールの ID

3. search_emails - クエリに一致するメールを検索します

   • パラメーター：
     • query：メールの各フィールドと照合する検索クエリ
     • max_results：返す結果の最大数（デフォルト：5）

4. send_email - 新しいメールを送信します

   • パラメーター：
     • to：宛先のメールアドレス
     • subject：メールの件名
     • body：メール本文

5. reply_to_email - 既存のメールに返信します

   • パラメーター：
     • email_id：返信するメールの ID
     • body：返信メッセージの本文

6. delete_email - 1 件のメールを削除します

   • パラメーター：
     • email_id：削除するメールの ID

7. delete_emails - 複数のメールを一括処理で削除します

   • パラメーター：
     • email_ids：削除するメール ID のリスト

設計方針

このプロジェクトでは、無駄を省いた効率的な設計方針を採用しています：

1. 冗長なコードを含まない最小限のコード
2. Gmail API との直接統合
3. モックデータや不要な抽象化を使用しない
4. 信頼性とパフォーマンスを重視

トラブルシューティング

サーバーポートの問題

サーバーポートに関する問題が発生した場合：

1. デフォルトのポート（8000）が使用中の場合、サーバーは利用可能なポートを自動的に探します
2. 実際に使用されたポートを確認するには、コンソールログを確認してください
3. .env ファイルで別のポートを手動で指定できます
4. Claude Desktop の設定で正しいポートが指定されていることを確認してください

認証の問題

認証に関する問題が発生した場合：

1. credentials.json ファイルがプロジェクトのルートに正しく配置されていることを確認してください
2. 再認証を強制するには、token.json ファイルが存在する場合は削除してください
3. OAuth クライアントで正しいスコープが有効になっていることを確認してください
4. 詳細なエラーメッセージを確認するには、コンソールログを確認してください

Gmail API のレート制限

Gmail API には、使用に影響する可能性のあるレート制限があります：

• 1 日あたり 1,000,000,000 クォータ単位
• API メソッドごとに消費するクォータ単位は異なります
• 詳細については、Gmail API のクォータを参照してください