Gmail MCP

Gmail MCP

日本語 | Русский

A1 Gmail MCPを使うと、AI アプリから自然な言葉で Gmail のメールボックスを操作できます。メールを検索・閲覧したり、返信を下書きとして準備したり、準備ができたら送信したり、ラベルを整理したり、完全に削除する代わりにゴミ箱を利用したりできます。

Google アカウントで Gmail API を使用します。編集可能な下書きと取り消せない送信済みメールを区別し、すべてのメール操作が元に戻せるかのように誤解させるのではなく、Gmail API の制限を明示します。

• 24 個のツール。 メッセージやスレッドの検索・閲覧、メールの直接送信または下書き経由での送信、下書きのライフサイクル、ラベル、ゴミ箱の管理に対応しています。
• 会話から接続できます。 「Gmail に接続」と言うと、サーバーが OAuth クライアントの設定を案内し、PKCE を使って 127.0.0.1 への Google のリダイレクトを受け取り、トークンをサーバー内で保持します。設定ファイルも再起動も不要です。
• 慎重に送信します。 下書き → 確認 → 送信の手順を重視しています。送信は破壊的操作として表示され、曖昧な失敗の後にサーバーが再送信することはありません。メールは送信後に取り消せません。
• ゴミ箱が安全網になります。 メールの削除は元に戻せるゴミ箱を経由します（約 30 日間）。意図的に、メッセージを完全に削除するツールはありません。
• 読み取りに上限があります。 デコードされた本文は明示された上限で切り詰められ、添付ファイルはメタデータとして返されるため、長いニュースレターが気付かないうちに会話を埋め尽くすことはありません。
• Google のスコープを最小限にしています。 gmail.modify のみを使用し、完全削除や Gmail 設定へのアクセスは行いません。

まずは読み取り専用の質問から始めましょう。

先週届いた未読メールを表示して、返信が必要なものを教えてください。

サーバーを接続する · 使用例を見る · 技術ドキュメントを開く

1 分で使い方を見る

あなた： 今週、Acme 契約について受信トレイに届いた未読メールは何ですか？

アシスタント： Gmail の検索クエリ構文を使って検索し、送信者、件名、日付、スニペットを表示します。何も変更されません。

あなた： 一番新しいメールへの返信を下書きしてください。署名済みのコピーを金曜日に送る、と伝えてください。

アシスタント： 同じスレッドに下書きを作成し、確認用に表示します。送信はされません。

あなた： 送信してください。

アシスタント： 下書きを送信します。送信は独立した明示的な破壊的操作なので、AI アプリは事前に確認を求めることができます。

目次

• クイックスタート
• できること
• メールの変更方法
• 変更できる内容
• アクセス権の取得
• 設定
• データ、制限、バックグラウンド処理
• 技術ドキュメント
• サポート

クイックスタート

Node.js 20+ と Google アカウントが必要です。インストール時に認証情報は不要です。サーバーは会話から接続します。

1. AI アプリにサーバーを追加します。
2. 「Gmail に接続して」と伝えます。設定ファイルを編集せずに、アシスタントがOAuth クライアントの作成とアクセスの承認を案内します。
3. 上記の読み取り専用の質問をします。

codex mcp add google-gmail \
  -- npx -y mcp-google-gmail@latest

codex mcp list

claude mcp add \
  --transport stdio --scope user google-gmail \
  -- npx -y mcp-google-gmail@latest

claude mcp list

{
  "mcpServers": {
    "google-gmail": {
      "command": "npx",
      "args": ["-y", "mcp-google-gmail@latest"]
    }
  }
}

{
  "mcpServers": {
    "google-gmail": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-gmail@latest"]
    }
  }
}

{
  "servers": {
    "google-gmail": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-gmail@latest"]
    }
  }
}

できること

受信トレイを整理する

• 過去 7 日間の未読メッセージを表示し、送信者ごとにグループ化します。
• Acme との契約に関するスレッドを見つけ、古い順に要約します。
• 添付ファイルが届いているメッセージはどれですか？件名とファイル名を表示します。

メールを作成して送信する

• このスレッドへの返信として、署名済みの書類を金曜日に送ると伝える下書きを作成します。
• 下書きを見せて、表現を簡潔にしてから送信します。
• マネージャーを CC に入れて、チームに短い状況報告メールを送信します。

メールボックスを整理する

• ラベル Receipts/2026 を作成し、該当するメッセージに適用します。
• 今週のニュースレターを既読にしてアーカイブします。
• そのスレッドをゴミ箱に移動します。気が変わったら元に戻します。

メールに対する変更

1. 安全に送信するには、下書きを使います。create_draft でメールを準備し、get_draft でレビュー用に表示してから、send_draft で送信します。send_message は下書きを経由せず、すぐに送信します。
2. 送信済みのメールは、外部に配信されると取り消せません。タイムアウトや 5xx エラーが発生してもサーバーは再送しません。再試行する前に in:sent を検索してください。送信を再実行すると、メールが二重に送信されるためです。
3. メッセージまたはスレッドを削除すると、ゴミ箱に移動します。manage_trash で約30日間は元に戻せます。完全に削除するツールは意図的に用意していません。
4. 下書きは例外です。update_draft は下書き全体を置き換えます（API では部分編集ができません）。delete_draft は完全に削除します。下書きはゴミ箱を経由しないためです。

すべての呼び出しは1つのメールボックス、つまりトークンを許可したアカウントを対象とします。デコードした本文は設定可能な上限で切り詰められ、その旨が明示されます。また、添付ファイルはメタデータのみ返されます。添付ファイルの内容は、意図的に raw_request を通じて取得します。

変更できる内容

確認プロンプトは AI クライアントが制御します。サーバーは、クライアントが閲覧と実際の変更を区別できるよう、読み取り、書き込み、破壊的なツールを識別します。

アクセスの取得

Google Gmail では OAuth 2.0 が必要です。API キーだけでは利用できません。接続方法は2つあります。1つ目は設定ファイルが不要です。

チャットから接続する（推奨）

「Gmail に接続して」と伝えると、アシスタントが一緒に手順を進めます。

1. setup_instructions でチェックリストを表示します。Google Cloud プロジェクトを作成または選択し、Gmail API を有効にして、同意画面を設定し、Desktop app の OAuth クライアントを作成します。
2. そのクライアントの JSON（「Download JSON」）をダウンロードし、そのパスをアシスタントに伝えます。set_client が所有者のみアクセス可能な状態で保存します。シークレットが会話を通じて送信されることはありません。
3. start_login が Google の同意リンクを返します。このマシン上でリンクを開いて承認してください。コードはチャットを経由せず、127.0.0.1 のワンショットリスナー（PKCE）に返されます。
4. finish_login がコードを交換し、トークンを ~/.config/mcp-google-gmail/credentials.json（mode 0600）に保存して、実際の Gmail API 呼び出しで検証します。そのため、まだ無効になっている API があれば、その場で検出されます。

トークンは呼び出しごとに再読み込みされるため、接続はすぐに使えます。AI アプリの再起動は不要です。auth_status で接続状況を確認でき、logout で接続を取り消して認証情報を削除できます。

環境変数（CI、無人インストール）

1. Google Cloud プロジェクトを作成または選択し、Gmail APIを有効にします。

2. OAuth 同意画面を設定し、Desktop app の OAuth クライアントを作成します。

3. 接続するメールボックスを持つ Google アカウントを認証します。すべての呼び出しは、そのメールボックスに対して動作します。OAuth 2.0 Playgroundでは、Use your own OAuth credentials を有効にすると、リフレッシュトークンを取得できます。

4. 次のスコープをリクエストします。

   https://www.googleapis.com/auth/gmail.modify
   

   このスコープで、検索、読み取り、送信、下書き、ラベル、ゴミ箱を操作できます。ただし、完全削除と Gmail の設定は対象外です。raw_requestによる完全削除には、さらに完全な https://mail.google.com/ スコープが必要です。

テストモードの OAuth リフレッシュトークンは、7 日後に期限切れになる場合があります。長期間アクセスする必要がある場合は、OAuth アプリを公開するか、Workspace ドメインの内部アプリを使用してください。クライアントシークレットとリフレッシュトークンは、パスワードとして取り扱ってください。

設定

すべての変数は任意です。何も設定しない場合、サーバーはチャットから接続します。

* OAuth の 3 つの値、またはアクセストークンのいずれかを指定してください。

データ、制限、バックグラウンド処理

• リクエストは Gmail に送信されます。 ローカルサーバーは Google OAuth トークンを更新し、Gmail API を呼び出します。匿名テレメトリに含まれるのは、インストール ID、パッケージのバージョン、AI クライアントとプラットフォームのバージョン、ツール名です。OAuth トークン、メールの内容、ツールの引数、プロンプトは含まれません。オプトアウトするには、ASKADS_TELEMETRY=0を設定してください。
• Google はクォータユニットを計上します。 Gmail のクォータはユーザーごとに毎秒約 250 ユニットです。メール送信には 100 ユニット、一般的な読み取りには 5 ユニットかかります。個人アカウントでは 1 日に約 500 通、Workspace アカウントでは約 2,000 通のメールを送信できます。429の場合、サーバーはバックオフを行います。読み取りはネットワークエラーと5xxエラーの後にも再試行しますが、送信やその他の書き込みは、結果が不確かな障害の後に再実行されることはありません。
• バックグラウンドポーリングはありません。 サーバーは呼び出されたときだけ実行されます。AI アプリがスケジュール済みタスクに対応している場合、定期的に受信トレイを確認できます。また、raw_requestを使ってhistory.listにアクセスし、差分同期を行うこともできます。

技術ドキュメント

• MCP 機能カタログ — 各ツールのタスク別ページ。
• すべてのツールと入力
• 開発ドキュメント
• 公開ドキュメント
• Gmail API リファレンス

サポート

バグを見つけた場合や、対応してほしいシナリオがある場合は、issue を作成するか、Telegramにご連絡ください。

最後まで読んでいただき、ありがとうございます！