CC for Biz
2026/05/01Claude Code
Skills活用AI活用ツール比較

Gmail MCP セットアップ完全ガイド｜詰まりどころ11箇所

Gmail MCP セットアップ完全ガイド｜詰まりどころ11箇所

Gmail MCP セットアップで最初に詰まる「Google Cloud側の準備」

Claude Code から Gmail を操作したい。具体的には、未読メールを取得して、AIに4象限で分類させ、それぞれに返信ドラフトを下書き保存する。こういうワークフローを組もうとすると、まず最初にぶつかるのが サードパーティ製 Gmail MCP（@gongrzhe/server-gmail-autoauth-mcp）のセットアップです。

私は普段、中小企業向けのAI業務自動化を受託している立場で、最近もビジネスオーナー向けに「Gmail返信ドラフトの自動生成」を Claude Code で構築する案件を進めています。その実装過程で、Google Cloud Console の挙動や OAuth 同意画面の落とし穴に何度も足を取られたので、本記事では「同じところで詰まらないための完全手順」を、ハマりどころに絞って解説します。

なぜ公式リモートMCPではなくサードパーティ版を選ぶかについては、以下の比較記事に整理しています。本記事はその続編・実装ガイド編として、サードパーティ版を選んだ前提で書きます。

Gmail MCPの選び方｜公式とサードパーティを実装視点で比較
Claude CodeGmail MCPの選び方｜公式とサードパーティを実装視点で比較

結論から言うと、躓きの9割は「セットアップ手順そのもの」ではなく、Google Cloud Console の細かい仕様と、credentials.json の置き場所の固定ルールにあります。これらを順番に潰していけば、初回でも30〜45分でゴールに到達できます。

Gmail MCPセットアップの全体像とハマりどころ

セットアップの全体像（6ステップ）

ゴールは「Claude Code を起動して /mcp list で gmail サーバーが connected と表示され、Gmail操作ができる状態」です。そのために通る6ステップは以下のとおりです。

  • ステップ1: 前提条件の確認（Node.js / Googleアカウント）
  • ステップ2: Google Cloud Console の準備（プロジェクト作成・Gmail API有効化・OAuth同意画面・スコープ・OAuthクライアントID）
  • ステップ3: credentials の配置（gcp-oauth.keys.json を ~/.gmail-mcp/ に置く）
  • ステップ4: 初回認証（npx auth でブラウザ認証）
  • ステップ5: Claude Code への接続（.mcp.json の記述）
  • ステップ6: 動作確認（/mcp list と簡単な操作テスト）

所要時間の目安は、Google Cloud Console を一度も触ったことがない方で 45〜60分、慣れていれば 15〜20分です。私自身も初回は同意画面の構成で30分ほど迷いました。一番時間がかかるのは Google Cloud側で、Claude Code 側の設定はほぼ一瞬です。

ステップ1: 前提条件の確認

必要なものは2つだけです。

  • Node.js（v18以上を推奨）
  • Googleアカウント（Gmail を実際に読み書きしたいアカウント）

Node.js のバージョン確認は以下のコマンドで行います。

node -v
# v18.x.x 以上であればOK

v16以下の場合は、nvm 経由で v18 以上にアップデートしておきましょう。Claude Code 自体が Node.js v18+ を要求するため、ここはセットで揃える必要があります。

もう1点だけ気をつけたいのが、Google Cloud のプロジェクト所有者と、実際に Gmail を読み書きするアカウントは同じである必要はないという点です。詳しくはステップ2の最後で触れます。

ステップ2: Google Cloud Console の準備

このステップが一番ボリュームがあります。落ち着いて順番に進めれば必ず通ります。

2-1. プロジェクト作成

Google Cloud Console を開き、画面左上の「プロジェクト選択」プルダウンから「新しいプロジェクト」を作成します。プロジェクト名は任意で構いません。私は gmail-mcp-verify のように、用途がわかる名前を付けています。

2-2. Gmail API の有効化

左サイドバーから「APIとサービス」→「ライブラリ」を選び、検索ボックスに「Gmail API」と入力します。「Gmail MCP API」のような名前のものは存在しないので、純粋な「Gmail API」を選んで「有効にする」をクリックします。

ここで間違って Google Workspace Admin SDK や People API などを有効化しても害はないですが、必須なのは Gmail API ひとつだけです。

2-3. OAuth 同意画面の構成

左サイドバーの「APIとサービス」→「OAuth同意画面」（新UIでは「ブランディング」）を開きます。ここで User Type は External（外部）一択です。

  • External: 一般のGmailアカウントが対象。個人利用ならこちら
  • Internal: Google Workspace 組織内ユーザー専用。一般のGmailでは選択不可

External を選んだら、以下の項目を埋めます。

  • アプリ名: ユーザー認証時の確認画面に表示される名前。「Gmail MCP Verify」などでOK
  • ユーザーサポートメール: GCPプロジェクト所有者の Gmail アドレスを選択
  • デベロッパー連絡先情報: 同じく自分のメールアドレス

「アプリ名」と「ユーザーサポートメール」は何を入れればいいか迷いがちですが、深く考える必要はありません。アプリ名は同意画面に表示されるラベル、サポートメールは自分の連絡先という認識で十分です。

2-4. テストユーザーの追加（最重要）

External で同意画面を作ると、初期状態は「テストモード」になります。テストモードでは、事前にテストユーザーとして登録したアカウントしか OAuth 認証を通れません。

左サイドバーの「対象」（または「Audience」）から「テストユーザー」セクションを開き、「ユーザーを追加」で Gmail を実際に読み書きしたいアカウントのメールアドレスを追加します。

このステップを忘れると、後の認証フローで「アクセスがブロックされました」「このアプリはGoogleの確認プロセスを完了していません」というエラーで止まります。私もここで一度躓きました。

なお、テストモードのまま運用して問題ありません。本番公開には Google の審査が必要で、自分用に使う分には審査を通す必要はありません。

2-5. スコープの追加

新UIだとここが一番迷子になりやすいポイントです。左サイドバー「データアクセス」を開き、「スコープを追加または削除」をクリックします。

表示されるフィルタに gmail.modify と入力し、該当行のチェックボックスをONにして「更新」を押します。最後に画面下の「保存」を必ずクリックしてください。

  • https://www.googleapis.com/auth/gmail.modify — メールの読み取り・送信・ドラフト作成・ラベル操作に必要

このスコープを追加し忘れると、認証フロー自体は通るのに、API呼び出し時に「権限不足」のエラーが出て詰まります。「認証は通ったのに動かない」場合の9割はスコープ追加忘れと思っていいです。

なお Google のドキュメントによれば gmail.modify は「sensitive scope（機密スコープ）」に分類され、本番公開する場合は Google の審査が必要になります。テストユーザーに自分のアドレスを追加した状態で使う限り、審査なしで利用可能です（Sensitive scope verification 公式ドキュメント参照）。

2-6. OAuth クライアントIDの作成

左サイドバー「APIとサービス」→「認証情報」を開き、「認証情報を作成」→「OAuthクライアントID」を選びます。

ここで重要なのが、アプリケーションの種類は「デスクトップアプリ」を選ぶことです。「ウェブアプリケーション」を選ぶとリダイレクトURIの登録が必要になり、ローカルで動作する gongrzhe版の設計と相性が悪くなります。

  • OK: デスクトップアプリ（リダイレクトURIの登録不要、localhost コールバック自動対応）
  • NG: ウェブアプリケーション（後の npx auth でエラーになる確率が高い）

クライアント名は任意。作成すると JSON 形式の credentials がダウンロードされます。これが次のステップで必要になります。

Google Cloud Console での6つの設定ポイント

ステップ3: credentials の配置

ダウンロードした JSON ファイルを ~/.gmail-mcp/gcp-oauth.keys.json として配置します。ファイル名は完全固定で、別名のままでは gongrzhe版が認識しません。

# ディレクトリ作成
mkdir -p ~/.gmail-mcp

# ダウンロードしたファイルをリネームして配置
mv ~/Downloads/client_secret_xxxxx.json ~/.gmail-mcp/gcp-oauth.keys.json

ここでつまずきやすいのは以下の3点です。

  • mkdir -p を忘れて「No such file or directory」エラーになる
  • ファイル名を oauth.json や credentials.json にしてしまい認識されない
  • ダブルクリックで開いた中身を別ファイルにコピペしようとして JSON が壊れる（普通に mv でファイルごと動かすのが正解）

配置後は ls ~/.gmail-mcp/ で gcp-oauth.keys.json が存在することを確認しましょう。

ステップ4: 初回認証（npx auth）

ターミナルで以下のコマンドを実行します。

npx @gongrzhe/server-gmail-autoauth-mcp auth

初回はパッケージのダウンロードに30秒〜1分ほどかかります。その後、自動的にブラウザが立ち上がり、Google のログイン画面が表示されます。ここで必ず、ステップ2-4でテストユーザーに追加したアカウントでログインしてください。別アカウントでログインすると即ブロックされます。

「未確認のアプリ」警告への対処

ログイン後、こんな画面が出ます。

Google hasn't verified this app
The app is requesting access to sensitive info in your Google Account.
Until the developer (you@example.com) verifies this app with Google, you shouldn't use it.

慌てずに、画面下の「Advanced」→「Go to {App Name}（unsafe）」をクリックします。これは自分が作ったアプリなので「unsafe」と書かれていますが、正しいテストユーザーで進めば問題ありません。

同意画面で「許可」を押すと、~/.gmail-mcp/credentials.json が生成されます。以下のコマンドで存在確認しましょう。

ls ~/.gmail-mcp/
# gcp-oauth.keys.json
# credentials.json   <- これが生成されていればOK

credentials.json が生成されていない場合は認証フローが途中で失敗しています。ブラウザのアドレスバーにエラーパラメータが付いていないか、ターミナルにエラーメッセージが出ていないかを確認してください。

ステップ5: Claude Code への接続

使いたいプロジェクトのディレクトリ直下に .mcp.json を作成し、以下を記述します。

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["@gongrzhe/server-gmail-autoauth-mcp"]
    }
  }
}

ここでよくあるミスが「.mcp.json をホームディレクトリに置いてしまう」というもの。Claude Code は cd した先のディレクトリの .mcp.json を読みます。プロジェクトルート（CLAUDE.md と同じ階層）に置くのが原則です。

ホームディレクトリ直下に置きたい場合は、Claude Code をホームディレクトリで起動する必要がありますが、CLAUDE.md の管理が複雑になるのでおすすめしません。

ステップ6: 動作確認

該当プロジェクトのディレクトリで Claude Code を起動します。

cd /path/to/your-project
claude

起動後、以下のスラッシュコマンドで MCP の接続状態を確認します。

/mcp list

出力に以下のような行が含まれていれば接続成功です。

gmail: connected

続いて簡単な動作テストとして、Claude Code に「未読メールのタイトルを5件だけ教えて」と頼んでみましょう。Gmail から件名が返ってくれば、セットアップは完了です。

セットアップ完了後の活用イメージ

ハマりどころ総点検（11項目）

ここまでの手順で踏みやすい落とし穴を、独立してまとめておきます。詰まったときはこのリストを上から確認してください。

1. アプリ名・ユーザーサポートメールが何かわからない

アプリ名は同意画面に表示されるラベル名（自由記入）、サポートメールはGCPプロジェクト所有者のメールアドレス。深く考えなくてOK。

2. User Type が External しか選べない

これは正解です。Internal は Google Workspace 組織アカウント専用なので、一般の Gmail では External + テストユーザー追加が正規ルートです。

3. テストユーザーに自分のアドレスを追加し忘れる

認証時に「アクセスがブロックされました」と出る原因の最頻出パターン。「対象」または「Audience」セクションから追加します。

4. 同意画面のステータスを「本番公開」に変えてしまう

個人利用ではテストモードのままでOK。本番公開すると Google の審査プロセスが必要になり、個人利用には不向きです。

5. スコープ追加の場所がわからない

新UIでは左サイドバー「データアクセス」→「スコープを追加または削除」。フィルタに gmail.modify と入力するのが最短経路です。

6. OAuth クライアントの種類で「ウェブアプリケーション」を選んでしまう

必ず「デスクトップアプリ」を選びます。Web を選ぶとリダイレクトURIの登録が必須になり、npx auth がうまく動きません。

7. credentials.json のファイル名を間違える

ダウンロード時のファイル名は client_secret_xxxxx.json のような名前ですが、必ず gcp-oauth.keys.json にリネームします。固定名なので変更不可。

8. ~/.gmail-mcp/ ディレクトリを作り忘れる

mkdir -p ~/.gmail-mcp を忘れると mv でエラーになります。-p を付けると親ディレクトリも自動作成してくれるので安全。

9. 「未確認のアプリ」警告で進めなくなる

「Advanced」リンクをクリック → 「Go to {App Name}（unsafe）」で進めます。テストユーザーに登録済みなら必ず通ります。

10. GCPプロジェクト所有者と認証Gmailを混同する

GCPプロジェクト所有者は管理権限を持つだけで、実際にメールが読み書きされるのは npx auth 時にログインした Gmail です。credentials.json は認証 Gmail 単位で生成されるため、複数アカウントで動かしたい場合は credentials.json を退避してから再認証します。

11. .mcp.json の置き場所を間違える

Claude Code 起動時の カレントディレクトリの .mcp.json しか読まれません。ホームディレクトリではなくプロジェクトルートに配置するのが基本。

うまくいかないときのリセット手順

何度かやり直したくなることもあります。以下のコマンドでクリーンに戻せます。

# 認証だけやり直したい
rm ~/.gmail-mcp/credentials.json
npx @gongrzhe/server-gmail-autoauth-mcp auth

# OAuth クライアント自体をやり直したい
# -> Google Cloud Console の「認証情報」から該当クライアントを削除して作り直し
# -> 新しい gcp-oauth.keys.json を ~/.gmail-mcp/ に上書き

# スコープを変更したい
# -> 「データアクセス」から該当スコープを追加・削除して保存
# -> credentials.json を一度削除して再認証（既存トークンには新スコープが反映されないため）

特に スコープを後から追加したのに反映されない場合は、credentials.json を削除して再認証することで新スコープが付与されたトークンが取得できます。これも私が一度ハマったポイントです。

セットアップが終わると何ができるようになるか

ここまでで Claude Code から Gmail を操作できる状態が完成します。実際に私が組んだワークフローを一例として紹介します。

ユーザー: morning email

Claude Code:
  1. gmail.search_emails で未読メールを取得（is:unread）
  2. 各メールの本文・送信元を解析
  3. 「緊急 × 重要」「重要 × 非緊急」「緊急 × 非重要」「非緊急 × 非重要」の4象限に分類
  4. 各メールに対して、優先度に応じた返信ドラフトを gmail.draft_email で作成
  5. ドラフトURLとサマリーをマークダウンで返す

朝、Gmail を開くと、優先度順に並んだ返信ドラフトがすでに保存されている状態。これを5分でレビュー・微修正して送信ボタンを押すだけ、という運用が成立します。

具体的なワークフロー実装は別記事で扱う予定ですが、セットアップさえ通せば、こうした「業務時間そのものを削る」自動化が現実的に動かせるところが Gmail MCP の最大の価値です。

「公式と何が違うのか」「自分の運用環境ではどちらを使うべきか」をまだ整理しきれていない方は、先に以下の比較記事を読むことをおすすめします。本記事のセットアップが必要かどうかの判断材料になります。

Gmail MCPの選び方｜公式とサードパーティを実装視点で比較
Claude CodeGmail MCPの選び方｜公式とサードパーティを実装視点で比較

まとめ：詰まりポイントを先に潰せば30〜45分で動く

サードパーティ製 Gmail MCP のセットアップは、手順そのものは6ステップで完結しますが、Google Cloud Console の細かい仕様で詰まると一気に時間が溶けます。本記事で押さえた11個のハマりどころを順番に確認すれば、初回でも30〜45分でゴールに到達できます。

ポイントを再掲します。

  • OAuth 同意画面は External + テストユーザー追加が正規ルート
  • スコープは gmail.modify を必ず追加
  • OAuth クライアントは「デスクトップアプリ」一択
  • credentials は ~/.gmail-mcp/gcp-oauth.keys.json という固定名で配置
  • .mcp.json はプロジェクトルート、Claude Code は cd 先の設定を読む

セットアップが終われば、未読メールの自動分類・返信ドラフト自動生成・添付ファイル付き返信の自動化など、Gmail を起点にした業務自動化が一気に現実味を帯びます。「メール処理に1日1時間取られている」状態を、Claude Code で 10分に圧縮するための最初の関門。ここを越えれば景色が変わります。

← 記事一覧に戻る
Service

御社の業務に合わせたClaude Code導入支援

「AIツールを導入したが、現場で使われない」を終わらせる。
業務課題のヒアリングから設計、ハンズオン実践、運用定着まで一貫して支援します。

無料AI活用診断を受けるサービス詳細を見る →
© 2025 Fyve Inc. All rights reserved.