gmail-mcp-server

MCPサーバーは、Gmail API を介して Gmail メッセージを（オプションのファイル添付付きで）送信する1つのツール send_email を公開します。Claude Code 内でローカル stdio MCP サーバーとして使用するために構築されています。

スコープは意図的に狭くしています: gmail.send のみ（メールボックスへの読み取り・変更アクセスはなし）— メール送信だけを仕事とするツールへの最小権限です。

この README は実際の初回セットアップに基づいて書かれており、その過程で発生したすべてのエラーを含みます。上から下へ順に従えば、それらのエラーには遭遇しないはずです。

PowerShell に関する注意: && は Windows PowerShell ではコマンド区切り文字として機能しません（これは bash/cmd の構文です）。以下の複数コマンドの行はすべて別々の行として書くか、1行にしたい場合は ; を使用してください: cd C:\Users\GaneshGupta\gmail-mcp-server; python auth_setup.py

1. Google Cloud — API の有効化と OAuth 認証情報の作成

これに関する Google コンソールの UI は最近「OAuth consent screen」から Google Auth Platform に改名され、設定は左ナビの複数ページ（Branding / Audience / Clients / Data Access / Verification Center）に分割されています。以下の手順は現在の名称を使用しています。

1. console.cloud.google.com にアクセスします。新しいプロジェクトを作成するか、既存のプロジェクトを再利用してください。

2. APIs & Services → Library → 「Gmail API」を検索 → Enable。

3. APIs & Services → OAuth consent screen（ここで新しい Google Auth Platform セクションに移動します）→ Branding ページに入力します:

   • App name: 任意の名前（例: gmail-mcp-tool）

   • User support email: 自分の Gmail アドレス

   • Developer contact email: 自分の Gmail アドレス

   • ロゴ/App domain フィールドは今は空のままにしてください — 「incomplete configuration」エラーが発生した場合は、ステップ4で App domain に戻ります。 推測で記入せず、実際にそのエラーを見た場合だけ記入してください。

4. Audience ページ（左ナビ）→ Test users の下 → + Add users → 自分の Gmail アドレス（メールを送信するアドレス）を入力 → Save。

   「Add users」がブロックされた場合 — 黄色いバナーに "Your app's OAuth configuration is incomplete... Please visit the Branding page" と表示されたら — これは gmail.send が機密スコープであり、Testing のみのアプリでも App domain フィールドが空でないことを要求するためです。修正方法:

   • Branding → App domain に移動し、以下を入力:

     • Application home page: https://example.com

     • Application privacy policy link: https://example.com/privacy

     • Application terms of service link: https://example.com/terms

   • これで Authorized domains フィールドが表示されます。ドメインのみ（https:// プレフィックスなし）を入力してください:

     • 正しい: example.com

     • 間違い（「Invalid domain: must not specify the scheme」というエラーで拒否される）: https://example.com

   • Branding で Save します（「Branding changes saved!」というトーストが表示されるはずです）。

   • Audience → Add users に戻ってもう一度試してください — 今度は通るはずです。

   これらの URL は実際に機能する必要はありません — アプリが Testing ステータスの間、Google はそれらを検証しません。フィールドが入力されていればよいだけです。

5. Clients ページ（左ナビ）→ + Create client:

   • Application type: Desktop app

   • Name: 任意の名前（例: gmail-mcp-desktop）

   • Create → Download JSON（作成直後にボタンが表示されます）

6. ダウンロードされたファイルは client_secret_<long-id>.apps.googleusercontent.com.json のような名前になります。正確に client_secret.json にリネーム し、次の場所に移動してください:

   C:\Users\GaneshGupta\gmail-mcp-server\credentials\client_secret.json

   ファイル名が正確であることが重要です — gmail_auth.py はその名前でファイルを探し、一致しない場合は FileNotFoundError を発生させます（ここで最もよくある間違いです）。

Related MCP server: Gmail MCP Server

2. 依存関係のインストール

cd C:\Users\GaneshGupta\gmail-mcp-server
pip install -r requirements.txt

3. 初回ログイン

python auth_setup.py

何が起こるか:

1. ブラウザウィンドウが開き、通常の Google サインインが表示されます。

2. 「Google hasn't verified this app」 という画面が表示されます。これは想定内です — 自分の OAuth クライアントが Testing モードで機密スコープを要求しているためです。Continue をクリックします（旧 UI では: Advanced → Go to [app name] (unsafe)）。

3. 「Send email on your behalf」権限を許可します。

4. ブラウザに "The authentication flow has completed. You may close this window." と表示されます。

5. ターミナルに Authorized. Token saved to ...credentials\token.json と表示されます。

ステップ2で代わりに Error 403: access_denied / "has not completed the Google verification process... can only be accessed by developer-approved testers" が表示された場合 — あなたの Gmail アドレスがまだ Audience → Test users リストにありません。上記のステップ 1.4 に戻ってください。

これは一度だけ行います。以降、server.py は保存されたトークンを静かに更新するだけで、自分からブラウザを開くことはありません。

4. トークンの動作確認（任意ですが推奨）

python -c "from gmail_auth import load_credentials; c = load_credentials(); print('valid:', c.valid); print('scopes:', c.scopes); print('has refresh token:', bool(c.refresh_token))"

valid: True、scopes: ['https://www.googleapis.com/auth/gmail.send']、has refresh token: True が表示されるはずです。

5. Claude Code に登録する

claude mcp add gmail-sender --scope user -- python C:\Users\GaneshGupta\gmail-mcp-server\server.py

--scope user はこれをグローバルに登録します — コマンドを実行したセッションだけでなく、以降このマシン上のすべての Claude Code セッションで利用可能になります。すでに実行中のセッションには遡って表示されません — MCP サーバーはセッション開始時に読み込まれるため、新しいターミナル / 新しい claude セッションで確認してください。

確認:

claude mcp list

リストに gmail-sender が表示されるはずです。

6. 使用方法

（上記の登録後）どの Claude Code セッションでも、自然言語で次のように依頼するだけです:

jane@example.com に、件名「Following up」、本文「...」でメールを送信して — C:\path\to\file.pdf を添付

Claude Code が send_email ツールを直接呼び出します。セッションごとの追加設定は不要です。

ツールリファレンス

send_email(to, subject, body, attachments=None, cc=None, bcc=None, html=False)

• to / cc / bcc: カンマ区切りのアドレス

• attachments: 絶対パスのローカルファイルパスのリスト。合計 15MB の制限（Gmail の raw 送信上限は 25MB。生ファイル 15MB なら base64 エンコードによる増加 + ヘッダーの分の余裕が残ります）

• html: true に設定すると、プレーンテキストの代わりに HTML 本文を送信します

• 戻り値: {status, message_id, thread_id, to, subject, attachment_count}

トラブルシューティング一覧

注記

• credentials/client_secret.json と credentials/token.json は gitignore されています — 決してコミットしないでください。

• 別の Gmail アカウントから送信するには、credentials/token.json を削除して auth_setup.py を再実行してください。