google-mail-mcp

google-mail-mcp

Gmail を MCP ツールとして利用できます。メールを読み取っても、アシスタントに読まれることはありません。

MCP を stdio 経由で扱う、単一の Go バイナリです。お使いのマシン上で、クライアントのサブプロセスとして、ご自身の Google アカウントに対して動作します。ホストするサーバーもサービスアカウントも不要です。Google OAuth クライアントを作成して一度ログインすれば、更新トークンは OS のキーリングに保存されます。

このツールが扱うのはメールボックス内の情報です。カレンダー招待の予定、リンク先の Drive ファイル、Chat スペースは、それぞれの API を使うサーバーの担当です。

google-mail-mcp を選ぶ理由

すべてのメッセージはあなた以外の誰かが書いたもので、その一部は AI アシスタントを誘導するために書かれています。そのため、メールは呼び出しごとの境界トークンで囲まれたブロックとして返されます。メールを読む人には見えないテキスト（隠しスタイル、ゼロ幅文字、背景と同じ色のテキスト）は削除され、削除した量が記録されます。メッセージがリンクまたは埋め込んだものは取得されず、リンクのテキストがリンク先とは別のサイトを示している場合はフラグが付けられます。

説得されたアシスタントを危険にしかねない書き込み機能はありません。自動転送、転送を行うフィルター、委任は実装されていません。メッセージを転送すると、下書きに添付されます。送信機能は有効にしない限り登録されず、有効にした場合も下書きのみ送信できます。削除はゴミ箱への移動です。完全削除は有効にしない限り登録されず、有効にした場合は Google にメールへの完全アクセスを求める唯一の操作となります。

読み取りには上限があります。スレッドは文字数の予算内で新しいものから順に返され、引用返信や署名は、どれだけ省略したかを示す1行に折りたたまれます。また、省略した内容がある場合は、続きの取得方法が示されます。非 ASCII の件名、名前、ファイル名は、どの文字セットでもデコードされます。

インストール

go install github.com/mmedum/google-mail-mcp/v3/cmd/google-mail-mcp@latest

または、最新リリースからアーカイブ（amd64 および arm64 対応の Linux、macOS、Windows 用）を取得し、実行前に検証してください。

sha256sum -c checksums.txt --ignore-missing

# The checksum file is signed with a keyless Sigstore certificate tied to
# the release workflow's identity.
cosign verify-blob checksums.txt \
  --bundle checksums.txt.bundle \
  --certificate-identity-regexp 'https://github\.com/mmedum/google-mail-mcp/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

# And the archive itself carries build provenance.
gh attestation verify google-mail-mcp_*.tar.gz --repo mmedum/google-mail-mcp

すべてのアーカイブには SBOM が含まれています。ビルドは再現可能です。タグを再ビルドすると、同じバイト列が得られます。

Claude Desktop

各リリースには .mcpb バンドルも含まれています。これを開くと、Claude Desktop がサーバーをインストールし、クライアントの設定に含める設定項目（OAuth クライアント JSON、プロファイル、読み取り専用、3つのスイッチ、添付ファイル用フォルダー）を尋ねます。送信（enable_send）、完全削除（enable_destructive）、設定変更（enable_settings）は、有効にしない限りオフのままです。また、読み取り専用とこれらの機能は併用できません。このサーバーは呼び出しの前に確認を求めません。Claude Desktop では各ツールの実行を「一度だけ許可」または「常に許可」で承認します。「常に許可」したツールはその後確認なしで実行されるため、必要なツールがない限りスイッチはオフのままにしてください。

バンドルは、両方のアーキテクチャに対応した macOS、Windows、Linux 用です。SHA-256 は同じ署名済みの checksums.txt に記載されています。

バンドルではログインできません。バイナリもインストールし、google-mail-mcp login --client-secret <your client JSON> を一度実行してください。バンドルは同じ認証情報を使用します。

Google の設定

docs/gcp-setup.md に必要な手順がすべて記載されています。Gmail API を有効にした Cloud プロジェクト、同意画面、サーバーの実行方法に応じたスコープ、そして デスクトップアプリ OAuth クライアントを用意します。その後、次を実行します。

google-mail-mcp login --client-secret ~/path/to/client_secret.json
google-mail-mcp doctor

メールを読み取る Gmail スコープはすべて、Google が「制限付き」と呼ぶスコープです。自分で使う分には費用はかかりませんが、テスト中の外部クライアントでは、7日後に期限切れとなる更新トークンが発行されます。その場合の状況については docs/runbook.md を参照してください。

SSH 経由でログインする

コールバック先はリモートホストのループバックアドレスですが、ブラウザーはローカルにあるため、ポートを転送してください。 google-mail-mcp login --no-browser を実行すると、認証 URL と、選択されたポートに対応する正確な ssh -L コマンドが表示されます。そのコマンドを別のローカルターミナルで実行し、URL をローカルで開いてください。

クライアントを接続する

Claude Code：

claude mcp add google-mail -- google-mail-mcp

または、クライアントの設定ファイルで：

{
  "mcpServers": {
    "google-mail": {
      "command": "google-mail-mcp"
    }
  }
}

すべての設定は GMAIL_* 環境変数で、docs/configuration.md に一覧があります。まず把握しておくとよい設定は次のとおりです。GMAIL_READ_ONLY=true を設定すると、読み取りツールのみが登録され、読み取り専用アクセスが要求されます。GMAIL_LOCAL_DIR は、添付ファイルの保存先として指定できる唯一のディレクトリです。GMAIL_PROFILE を使うと、1 台のマシンで複数のアカウントを管理できます。

ツール

ツール	機能
get_profile	サインイン中のアカウント、その合計数、現在の履歴 ID
search_threads	Gmail 検索で会話を検索します
search_messages	Gmail 検索で個々のメッセージを検索します
get_thread	予算の範囲内で、新しい順に会話を読み込みます
get_message	ID または Message-ID ヘッダーを指定して、1 件のメッセージを読み込みます
read_attachment	添付ファイルのテキストを読み込みます。プレーンテキスト、CSV、Markdown、JSON、HTML、カレンダー、添付メールに対応します
list_labels	すべてのラベルを一覧表示します。件数の表示は任意です
list_drafts	未送信の下書き
get_draft	1 件の下書きを読み込みます
list_changes	履歴 ID 以降に変更された内容と、そのカーソルの有効期限が切れたかどうか
get_settings	転送、不在通知、差出人アドレス、IMAP、POP の設定を読み込みます。読み取り専用です
list_filters	アカウントのフィルターを一覧表示し、メールを転送するフィルターがあればその旨を示します
download_attachment	添付ファイルを GMAIL_LOCAL_DIR に保存します。上書きはせず、この変数が設定されている場合のみ使用できます
download_attachments	1 件のメッセージの複数またはすべての添付ファイルを同じ方法で保存します。GMAIL_LOCAL_DIR が設定されている場合のみ使用できます
create_draft	新しい下書き、サーバー側でスレッド化し、指定があれば親メッセージを引用する返信、または元のメールを添付する転送を保存します。送信はしません
update_draft	指定されたフィールドのみを変更します。読み込み後に変更された下書きは拒否します
delete_draft	含まれているメッセージを指定し、confirm: true を指定して下書きを完全に削除します
modify_labels	最大 100 件のメッセージまたはスレッドにラベルを追加・削除し、項目ごとに結果を報告します
trash	最大 100 件のメッセージまたはスレッドをゴミ箱に移動します。30 日間保持されます
restore	メッセージまたはスレッドをゴミ箱から取り出します
create_label	ユーザーラベルを作成します
update_label	ユーザーラベルの名前、または表示方法を変更します
send_draft	すべての宛先、件名、冒頭の一文を指定して下書きを送信します。GMAIL_ENABLE_SEND=true の場合のみ使用できます
delete_permanently	confirm: true を指定して、最大 100 件のメッセージまたはスレッドを完全に削除します。GMAIL_ENABLE_DESTRUCTIVE=true の場合のみ使用できます
delete_label	confirm: true を指定してユーザーラベルを削除します。GMAIL_ENABLE_DESTRUCTIVE=true の場合のみ使用できます
update_signature	アカウントのアドレスのいずれかに署名を設定します。GMAIL_ENABLE_SETTINGS=true の場合のみ使用できます
create_filter	今後受信するメールのフィルターを作成します。転送やゴミ箱への移動はできません。GMAIL_ENABLE_SETTINGS=true の場合のみ使用できます
create_trash_filter	confirm: true を指定して、条件に一致するメールが届いたときにゴミ箱へ移動するフィルターを作成します。GMAIL_ENABLE_SETTINGS=true と GMAIL_ENABLE_DESTRUCTIVE=true の場合のみ使用できます
delete_filter	条件を指定して confirm: true を指定し、フィルターを削除します。GMAIL_ENABLE_SETTINGS=true と GMAIL_ENABLE_DESTRUCTIVE=true の場合のみ使用できます
set_vacation	連絡先またはドメインに対する不在通知をオンにするか、オフにします。GMAIL_ENABLE_SETTINGS=true と GMAIL_ENABLE_SEND=true の場合のみ使用できます

検索では、q に Gmail 独自の検索言語を指定し、after と before には実際の時刻を指定します。Gmail は q 内の日付を 太平洋時間の午前 0 時として扱います。各結果には、消費したクォータが表示されます。書き込み操作ではすべて dry_run を指定し、対象を ID で明示します。また、Gmail からの応答に基づいて変更内容を示します。GMAIL_READ_ONLY=true にすると、書き込み操作は無効になります。最後の 8 つのツールは、対応する設定が有効でない限り登録されません。

呼び出しではなく添付するクライアントでは、gmail://threads/{id}、 gmail://messages/{id}、gmail://labels がそれぞれ get_thread、get_message、list_labels と同じテキストを提供します。

安全性

• メールはデータです。 メールは、隠された内容が除去され、件数が記録された状態で届きます。また、どのツールの説明も、モデルにメールに対して行動するよう指示しません。

• デフォルトでは、ほかの人に何も送信されません。 下書きは Gmail に保存され、送信を待ちます。また、デフォルトでは、どのツールも設定を変更しません。転送設定は表示されますが、設定されることはありません。

• 設定はオプトインです。 GMAIL_ENABLE_SETTINGS=true の場合、サーバーは署名を設定し、フィルターを作成できます。フィルターで転送はできません。メールをゴミ箱に入れるフィルターは、専用ツールの create_trash_filter を使います。このツールと delete_filter には、GMAIL_ENABLE_DESTRUCTIVE=true と confirm: true も必要です。休暇中の自動返信はほかの人に返信するため、GMAIL_ENABLE_SEND=true も必要です。返信先は連絡先またはアカウントのドメインに限られ、有効にするには confirm: true が必要です。

• 送信はオプトインで、下書きを介して行います。 GMAIL_ENABLE_SEND=true の場合、send_draft は保存されているとおりに下書きを送信します。スレッドの参加者を含むすべての宛先を confirm_recipients に明記する必要があります。また、呼び出しには下書きの件名と冒頭の一文が含まれるため、クライアントのプロンプトで送信内容を確認できます。Gmail が確認しなかった送信は、再度行われることはありません。

• 削除はゴミ箱への移動です。 Gmail では、ゴミ箱に入れたメールは30日間保持され、restore で元に戻せます。デフォルトで完全に削除されるのは delete_draft のみです。このツールには、下書きが保持するメッセージと confirm: true が必要です。delete_permanently と delete_label は、削除権限を持つ唯一のスコープも要求する GMAIL_ENABLE_DESTRUCTIVE=true が設定されている場合にのみ使用できます。どちらの呼び出しにも confirm: true が必要です。

• 各呼び出しはクライアントが承認します。 サーバー自体が承認を求めることはありません。claude.ai と Codex は、破壊的な操作としてマークされたツールについて、送信、設定変更、または取り消しできないすべての書き込みを求めるプロンプトを表示します。VS Code は、書き込みを行うすべてのツールについてプロンプトを表示します。Claude Code では、完全に削除されたメールはゴミ箱を経由せず、ラベルはすべてのメッセージから外されるため、設定に関係なく delete_permanently と delete_label は毎回確認を求めます。それ以外の呼び出しについては、設定の permissions.ask に、承認したい呼び出しを1つずつ列挙してください。google-mail の代わりに、サーバーに付けた名前を使います。たとえば、送信、設定変更、削除を行う書き込みは次のとおりです。

  {
    "permissions": {
      "ask": [
        "mcp__google-mail__send_draft", "mcp__google-mail__set_vacation",
        "mcp__google-mail__update_signature", "mcp__google-mail__create_filter",
        "mcp__google-mail__create_trash_filter", "mcp__google-mail__delete_filter",
        "mcp__google-mail__delete_draft", "mcp__google-mail__delete_permanently",
        "mcp__google-mail__delete_label"
      ]
    }
  }
  

  誰も監視していない状態で実行されるクライアントは、登録されているすべての書き込みを実行できます。そのため、GMAIL_ENABLE_SEND、GMAIL_ENABLE_DESTRUCTIVE、GMAIL_ENABLE_SETTINGS は無効のままにしておいてください。

• ファイルの保存先は1つのディレクトリです。 download_attachment と download_attachments は、GMAIL_LOCAL_DIR 内に安全な名前でのみ書き込み、既存のファイルを上書きすることはありません。

• ログにメールの内容が記録されることはありません。 アドレス、件名、本文、ラベル名、クエリは記録されず、IDは先頭6文字に切り詰められます。テストではマーカー値を使ってすべてのツールを実行し、ログに値が含まれた場合は失敗します。これにより、デバッグログを安全に貼り付けられます。

• クライアントのプロンプトを除く上記のすべては、サーバーで強制されます。ツールのアノテーションは設定されていますが、クライアントが無視する場合もあります。

docs/security.md に詳細がすべて記載されています。

サポートを受ける

まず google-mail-mcp doctor を実行してください。クライアントの JSON、トークン、付与されたスコープ、Gmail API が有効かどうかを確認し、不足しているものを示します。よくある予期しない問題については、docs/runbook.md をご覧ください。その後、doctor の出力とバージョンを添えてイシューを作成してください。ツールの結果は貼り付けないでください。 それはメールであり、ほかの人の言葉やアドレスが含まれています。

バージョニング

セマンティックバージョニングを採用しています。ツール名と出力フィールドが公開契約です。対応が必要な変更は CHANGELOG.md で Breaking として示されます。

開発

make check

これが CI で実行される内容です。各ゲートの内容とライブドライバーの仕組みについては、docs/development.md をご覧ください。

ドキュメント

docs/README.md が目次です。その設計、設計の根拠となるプラットフォームの仕様、Gmail API の各メソッドに対する評価は、docs/architecture.md に記載されています。

貢献

CONTRIBUTING.mdをご覧ください。

セキュリティ

脆弱性は非公開のアドバイザリを通じて報告してください。詳しくは SECURITY.mdをご覧ください。

行動規範

CODE_OF_CONDUCT.md。

ライセンス

Apache 2.0。