Gmail MCP Server

Gmail MCP Server とは？

Gmail MCP Server は、コミュニティが開発した Python 製の小規模な Gmail MCP サーバーです。Claude Desktop などの MCP クライアントが Gmail API 経由で最近の受信トレイを読み、メールを検索できるようにします。認証は OAuth2 で、要求するのは読み取り専用アクセスのみです。

このプロジェクトは GitHub ユーザー ajbr0wn が作成したもので（ソース：github.com/ajbr0wn/gmail-mcp-server）、Google 製ではありません。提供するのはリソース 1 つとツール 1 つだけで、メールの送信、削除、ラベル付けはできません。アシスタントにメールボックス内の調べものだけをさせたい場合に、範囲が狭くリスクの低い選択肢です。

Gmail MCP Server の使い方

サーバーは stdio でローカル実行します。必要なのは Python 3.12（README では conda 環境を使用）、Google Cloud プロジェクト、Gmail API 用の OAuth クライアントです。PyPI には公開されていないため、リポジトリをクローンしてインストールします。

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

1. Google Cloud Console でプロジェクトを作成します。
2. Gmail API を有効にします。
3. アプリケーションの種類を Desktop application として OAuth 2.0 認証情報を作成します。
4. ファイルをダウンロードし、credentials.json として保存します。

2. サーバーをインストールする

git clone https://github.com/ajbr0wn/gmail-mcp-server.git
conda create -n mcp-gmail python=3.12
conda activate mcp-gmail
cd gmail-mcp-server
pip install -e .

3. 必須の環境変数を 2 つ設定する

• GMAIL_CREDENTIALS_FILE：Google OAuth 認証情報ファイルのパス
• GMAIL_TOKEN_FILE：認証トークンの保存先パス（初回サインイン時に自動作成）

クライアントに組み込む前に、サーバーを直接起動してテストできます。

GMAIL_CREDENTIALS_FILE="/path/to/credentials.json" \
GMAIL_TOKEN_FILE="/path/to/token.json" \
python -m gmail_mcp_server.server

Claude Desktop

claude_desktop_config.json に次の内容を追加し、すべての /path/to/ を実際のパスに置き換えます。

{
  "mcpServers": {
    "gmail": {
      "command": "/path/to/conda/envs/mcp-gmail/bin/python",
      "args": ["-m", "gmail_mcp_server.server"],
      "env": {
        "PYTHONPATH": "/path/to/gmail-mcp-server/src",
        "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json",
        "GMAIL_TOKEN_FILE": "/path/to/token.json"
      }
    }
  }
}

Claude Desktop を再起動します。Claude が初めて Gmail にアクセスするとブラウザが開き、アプリを承認できます。以後トークンは GMAIL_TOKEN_FILE に保存され、自動的に更新されます。

Claude Code

README に記載があるのは Claude Desktop だけですが、stdio クライアントであれば同じコマンドと環境変数で起動できます。Claude Code の場合：

claude mcp add gmail \
  -e PYTHONPATH=/path/to/gmail-mcp-server/src \
  -e GMAIL_CREDENTIALS_FILE=/path/to/credentials.json \
  -e GMAIL_TOKEN_FILE=/path/to/token.json \
  -- /path/to/conda/envs/mcp-gmail/bin/python -m gmail_mcp_server.server

Cursor、VS Code などのクライアントでは、上記 Claude Desktop 設定の command、args、env をそれぞれの MCP 設定ファイルで再利用してください。

Gmail MCP Server の主な機能

• gmail://inbox/recent リソースで受信トレイの最新 10 件のメールを読み取ります。
• Gmail 標準の検索構文（from:、after:、subject: など）でメールを検索します。
• Gmail への読み取り専用アクセスのみを要求し、書き込み権限は求めません。
• 初回利用時にブラウザで OAuth2 サインインを行い、その後はトークンを自動更新します。
• 認証情報とトークンは指定したローカルファイルに保存されます。
• 起動、認証、リソースやツールの利用、エラーについて詳細なログを stderr に出力します。
• 小さな Python コードベースで、読みやすく拡張しやすい構成です。

Gmail MCP Server のツール

このサーバーにはツールが 1 つ、リソースが 1 つあります。

• search_emails は必須の query（任意の Gmail 検索文字列）と任意の max_results（デフォルト 10）を受け取ります。送信者、期間、件名、ラベルでメッセージを探すのに使います。
• gmail://inbox/recent はツールではなくリソースです。MCP リソースに対応したクライアントでは、これを添付して最新 10 件のメールをモデルのコンテキストとして渡せます。

メールの送信、下書き作成、アーカイブ、削除のためのツールはありません。

Gmail MCP Server のユースケース

• アシスタントから離れずに受信トレイを確認する：「最近のメールは何についての内容？」
• 特定のメッセージを探す：「Could you show me any emails from sanrio in the last two days?」（README 掲載の例）
• 領収書や確認メールから情報を抜き出す：「今月航空会社から届いたメールを検索して、予約番号を一覧にして。」
• 同じ送信者からの更新をまとめる：「今週 GitHub から届いたビルド失敗のメールを探して要約して。」
• コーディングや執筆の作業にメールの文脈を取り込む。たとえば別の場所で返信を書く前に顧客のバグ報告を確認する。

Gmail MCP Server と代替ツールの比較

• Google の Gmail MCP サーバー： Google は Google Workspace Developer Preview Program の一環として、リモートの Gmail MCP エンドポイント https://gmailmcp.googleapis.com/mcp/v1 を提供しています（設定ガイド）。Streamable HTTP と OAuth 2.0 を使い、ツールには search_threads、get_thread、create_draft やラベル管理が含まれます。Google がホストし下書き作成もできるサーバーが必要ならそちら、プレビュー登録なしでローカルの読み取り専用構成にしたいならこの Gmail MCP サーバーが向いています。
• 機能の多いコミュニティ製サーバー： ほかのオープンソース Gmail MCP サーバーには送信、ラベル、添付ファイルなどの機能があります。権限の範囲が広いため、実際のメールボックスに接続する前に要求される権限を確認してください。

Gmail MCP Server のトラブルシューティング

• ModuleNotFoundError: gmail_mcp_server： クライアントが別の Python を使っています。command を mcp-gmail 環境内のインタープリターに向け、PYTHONPATH をリポジトリの src フォルダに設定してください。
• 起動時に失敗する： GMAIL_CREDENTIALS_FILE と GMAIL_TOKEN_FILE の両方が設定されているか確認します。README では両方とも必須です。プレースホルダーではなく完全なパスを使ってください。
• ブラウザが開かない、または承認エラーになる： OAuth クライアントの種類が Desktop application であること、認証情報と同じ Google Cloud プロジェクトで Gmail API が有効になっていることを確認します。
• 再承認やアカウント切り替えが必要： Google アカウントの設定でアクセスを取り消し、トークンファイルを削除してから再実行すると、新しいサインインが始まります。
• 原因がわからない失敗： サーバーの stderr 出力を確認してください。認証状態やエラーがそこに記録されます。