Gmail Mcp

📧 gmail-mcp

MCP 対応 AI アシスタントから、Gmail の読み取り、検索、送信、下書き作成、ラベル付け、フィルタリング、スレッド管理を行えます。Gmail API をスコープで制御されるツールとプロセス内の安全対策でラップしています。

メモ

GongRzhe/Gmail-MCP-Server（2026-03-03 にアーカイブ）の強化・拡張フォークで、ArtyMcLabin/Gmail-MCP-Server を経由しています。分岐点以降、180 件以上のコミットと大規模な書き換えを行い、セキュリティ強化、Gmail の機能改善（全員に返信、送信元エイリアス、スレッド単位のツール、ディスクへのダウンロード、宛先の組み合わせ、リトライ付き一括操作など）、サプライチェーンの衛生管理、CI によるゲートを追加しました。すべての PR は、マージ前に CodeRabbit と 2 つのモデルによる Qodo Merge のレビューを受けます。セキュリティ対策と脅威モデルについては SECURITY.md を、親フォークとの差分については以下の比較表をご覧ください。

Claude Desktop、Claude Code、Cursor、Continue、OpenClaw などの AI アシスタントが、スコープで制御されるツールを通じて Gmail アカウントを読み取り、管理できる Model Context Protocol（MCP）サーバーです。実際に必要となる Gmail v1 API の機能（メッセージ、スレッド、ラベル、フィルタ、添付ファイル、下書き、全員に返信）を、単一の npx インストールで利用できます。

重要

位置づけ。 上流では、このフォークを maximalist と呼んでいます。外部から見れば正確な呼び名ですが、意図を誤って伝えています。klodr/gmail-mcp は、次の4つの特性を軸に構築されています。コード、テスト、CI/CD はすべて、この4つだけを支えるために存在します。

• セキュア — 入力のサニタイズ、宛先のペアリング、レート制限、送信者の解決、監査ログ記録を、運用者の注意力に頼るのではなく、サーバー内で徹底します。Gmail の機能は仲介されており、生のまま公開されていません。
• 自律性 — 人間がすべての操作を監視していなくても、安全を保てるように設計されています。上流の「自分の日常のワークフローで使う」という想定とは異なる脅威モデルです。プロセス内ミドルウェアが、その隔たりを埋めます。
• テスト済み — 43ファイルにわたる945件の vitest ケースで、99.37% のステートメントカバレッジ（ブランチカバレッジ91%）を達成しています。さらに、fast-check によるプロパティベースのファジングスイートと、専用のハードニングテストファイルも備えています。
• 加速する変化の中でも高いレジリエンス — 17の CI/CD ワークフロー（CodeQL、OSV、Gitleaks、leak-detect、Scorecard、Socket、SLSA、ロックファイルの lint、署名付きリリースなど）で、実際の変化の速さに合わせてセキュリティエコシステムを追跡しています。変化は数日単位、ときには数時間単位です。最近の具体例は qs CVE-2026-8723 で、公開勧告から数時間以内に検出され、klodr/* MCP ファミリー全体にリリースされました。

詳細な根拠と、ツールごとの設計上のトレードオフについては、docs/DESIGN_DECISIONS.md をご覧ください。

✨ なぜこの MCP なのか？

元の Gmail MCP サーバーから派生した、現在メンテナンス中の3つのフォークを比較します。エージェントプラットフォームが実際に必要とするもの、すなわちプロンプトインジェクション対策、サプライチェーンの完全性、運用上の健全性に焦点を当てています。

機能	GongRzhe/Gmail-MCP-Server（オリジナル、メンテナンス終了）	ArtyMcLabin/Gmail-MCP-Server（中間フォーク）	klodr/gmail-mcp（このリポジトリ）
Gmail の基本機能
メッセージの送信／下書き／閲覧／検索	✅	✅	✅
ラベルの CRUD	✅	✅	✅
フィルターの CRUD	⚠️ list_filters が動作しない	✅ 修正済み	✅
一括変更／削除	✅	✅	✅
返信のスレッド化（In-Reply-To／References）	❌ 返信が孤立する	✅	✅
全員に返信するツール	❌	✅	✅
送信エイリアス（from パラメーター）	❌	✅	✅
返信と転送は、Gmail のウェブ UI と同様に、会話で使用されているエイリアスから送信されます。reply_all では自身のエイリアスがコピーされません（トークンが送信エイリアス一覧を読み取れる場合）	❌	❌	✅
スレッド単位のツール（get_thread、list_inbox_threads、get_inbox_with_threads）	❌	✅	✅
メールをディスクにダウンロード（json／eml／txt／html）	❌	✅	✅
添付ファイルのダウンロード	✅	✅	✅
メッセージの添付ファイルをすべて一度にダウンロードし、必要に応じて 1 つの ZIP にまとめる（元のファイル名を保持）	❌	❌	✅
read_email に Cc／Bcc の行を表示（返信と全員に返信のどちらにするか判断可能）	❌	✅	✅
OAuth／認可
最小権限での認証に使用する --scopes フラグ	❌	✅	✅
付与されたスコープに基づいてツール一覧をフィルタリング	❌	✅	✅
OAuth 認証情報ファイルのモード 0o600	❌	✅	✅
OAuth のループバックコールバックを state と PKCE（S256）で検証し、傍受された認可コードを使用できないようにする	❌	❌	✅
プロジェクトフォルダーに残された gcp-oauth.keys.json は auth でのみインポートされ、通常の起動時にはインポートされない	❌ 毎回の起動時にコピー	❌ 毎回の起動時にコピー	✅
セキュリティ — 入力処理
CRLF ヘッダーインジェクションのサニタイズ（\r\n\0）	❌	⚠️ 部分的	✅
download_attachment におけるパストラバーサル	❌	✅ 修正済み	✅
プロンプトインジェクションによる情報流出を防ぐパス隔離（添付ファイルのソース＋ダウンロード先）	❌	❌	✅
シンボリックリンクに安全な書き込み（O_NOFOLLOW ＋ mkdir 後の実パス再検証、TOCTOU 対策）	❌	❌	✅
maxResults／batchSize／messageIds の長さに対する Zod の上限	❌	❌	✅
暗号学的に安全な MIME 境界（Math.random ではなく crypto.randomBytes）	❌	❌	✅
セキュリティ — 送信メールとプロンプトインジェクション
受信者の許可リスト（GMAIL_MCP_RECIPIENT_PAIRING）を任意で設定可能：送信、返信、転送、下書きはペアリング済みのアドレス宛てに限られる	❌	❌	✅
許可リストが有効な場合、モデルは gmail-mcp を通じて許可リストを拡張できません。人間が MCP クライアントで確認するか、npx @klodr/gmail-mcp pair add を実行します	❌	❌	✅
アカウントの送信エイリアスに含まれない from は、送信エイリアス一覧を読み取れて、かつ一覧が空でない場合は拒否されます。これにより、Gmail がデフォルトのアドレスから黙って送信するのを防ぎます	❌	❌	✅
send_draft は、To／Cc／Bcc がアドレスとして解析できない下書きの送信を拒否します	—（send_draft なし）	❌	✅
ツールファミリーごとに 24 時間および 30 日間の書き込み上限を設定。一括ツールでは呼び出し回数ではなく、メッセージごとにカウント	❌	❌	✅
メールを転送するフィルターは拒否されます（転送ルールは、一致する今後のすべてのメールを気付かれずに転送します）	❌ create_filter が action.forward を受け付ける	❌ create_filter が action.forward を受け付ける	✅ 理由とともに拒否
ダウンロードしたファイルにインターネットから取得したことを示すマークを付与（macOS の検疫、Windows の Mark of the Web。Mail や Outlook と同様）	❌	❌	✅
エクスポートした HTML：スクリプト、フレーム、フォームをブロック。指定がない限り、リモート画像、スタイルシート、フォント、メディア（トラッキングピクセル）をブロック	—（HTML エクスポートなし）	❌ CSP なし	✅
MCP プロトコルとツール機能
MCP SDK バージョン	v0.4.x	v1.27.x	v1.32.x
ツールアノテーション（readOnlyHint／destructiveHint／idempotentHint）	❌	✅	✅
llms-install.md（LLM が読み取れるインストールガイド）	❌	❌	✅
公開／発見性
npm で公開	❌ 古く、今後のリリースなし（リポジトリはアーカイブ済み）	❌（中間フォークから GitHub インストールとして利用）	✅ 専用のスコープ付きパッケージ、署名済みリリース
メンテナンス状況（直近 30 日）	❌（2026-03-03 にアーカイブ済み）	⚠️ 不定期	✅ 毎日のレビューサイクル（CodeRabbit ＋ 人間）
サプライチェーンの完全性
Node.js の最低バージョン	❌ >=14（2023 年 4 月に EOL）	❌ >=14（2023 年 4 月に EOL）	✅ >=24.18.1（Node 24 および 26 でテスト済み）
CI：CodeQL Advanced（javascript-typescript ＋ actions）	❌	❌	✅
CI：OpenSSF Scorecard（週次スキャン＋バッジ）	❌	❌	✅
CI：Socket Security のサプライチェーンアラート	❌	❌	✅
CI：すべての PR に対する CodeRabbit の積極的なレビュー	❌	❌	✅
リリース：署名済みビルド（Sigstore ＋ SLSA in-toto 証明書 ＋ npm provenance）	❌	❌	✅
リリース：単一ファイルの ESM バンドル	❌	❌	✅
テスト
単体テスト／プロパティテスト	❌（テスト 0 件）	⚠️（テスト 97 件）	✅（テスト 945 件、43 ファイル）
src/** 全体のステートメントカバレッジ	0%	16.14%	99.37%（ブランチ 91%）
fast-check によるプロパティベースのファズテストスイート	❌	❌	✅
セキュリティ強化専用のテストファイル（隔離、CRLF、O_EXCL）	❌	❌	✅
CI/CD のセキュリティ強化
シェルインジェクションに安全な GitHub Actions ワークフロー	❌	✅	✅
最小権限の permissions: スコープを使用するワークフロー	❌	✅	✅
すべての GitHub Actions を完全なコミット SHA で固定	❌	❌	✅
運用
CHANGELOG.md（Keep-a-Changelog）	❌	❌	✅
SECURITY.md（脆弱性の報告）	❌	❌	✅
klodr/gmail-mcp は、3つの中で唯一、（a） プロンプトインジェクションによる添付ファイルの持ち出しを無効化するソースパスの隔離、（b） 悪意のあるメールでモデルを説得して回避できない送信ガードレール（gmail-mcp を介してモデルが拡張できない任意の宛先許可リスト、転送フィルターなし、すべてのメッセージをカウントする書き込み上限）、（c） 最新のサプライチェーン（Scorecard、Socket、Sigstore）、（d） マージ前にすべての PR が通過しなければならない、リポジトリ内のレビュー方針（.coderabbit.yaml）を備えています。

フォークの各列は、GongRzhe a890d19（2025-08-06、アーカイブ済み）および ArtyMcLabin 83e8daf（main、2026-08-12）のコードと照合しています。

📦 インストール

npm install -g @klodr/gmail-mcp

または、npx から直接実行します。

npx -y @klodr/gmail-mcp

Node.js 24.18.1 以降が必要です（Node 24 と 26 でテスト済み）。

⚙️ 設定

1️⃣ Google Cloud OAuth 認証情報

1. Google Cloud Console を開きます。
2. プロジェクトを作成し、Gmail API を有効にします。
3. APIs & Services → Credentials で、OAuth 2.0 Client ID（Desktop または Web）を作成します。Web の場合は、承認済みのリダイレクト URI に http://localhost:3000/oauth2callback を追加します。
4. JSON をダウンロードして gcp-oauth.keys.json に名前を変更し、~/.gmail-mcp/gcp-oauth.keys.json に配置します（または GMAIL_OAUTH_PATH=/abs/path/gcp-oauth.keys.json で上書きします）。

2️⃣ 認証（初回のみ）

npx -y @klodr/gmail-mcp auth --scopes=gmail.readonly

実際に必要な最小限のスコープを指定して、必ず --scopes を渡してください。MCP は許可されたスコープに基づいて起動時にツールの一覧をフィルタリングするため、読み取り専用トークンでは書き込みツールが LLM に公開されません。Google の同意フローを行うためにブラウザーが開き、トークンは ~/.gmail-mcp/credentials.json に書き込まれます（モード 0o600）。

3️⃣ MCP クライアントにサーバーを登録

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

クライアントごとの設定ファイル：

• Claude Code：~/.claude.json
• Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json（macOS）／%APPDATA%\Claude\claude_desktop_config.json（Windows）
• Cursor：~/.cursor/mcp.json
• OpenClaw：~/.openclaw/openclaw.json

LLM で読み取れるインストールガイドについては、llms-install.md を参照してください。

🔑 OAuth スコープ

スコープの略称	Gmail スコープの完全名	許可される操作
gmail.readonly	…/auth/gmail.readonly	メッセージ、スレッド、ラベルの読み取り（フィルターツールには gmail.settings.basic が必要です）
gmail.modify	…/auth/gmail.modify	読み取り専用の操作に加え、ラベルの適用／削除、メッセージの削除
gmail.compose	…/auth/gmail.compose	下書きの作成
gmail.send	…/auth/gmail.send	メッセージの送信
gmail.labels	…/auth/gmail.labels	ラベルの管理のみ
gmail.settings.basic	…/auth/gmail.settings.basic	フィルターの管理

設定例：

# Read-only browsing
npx @klodr/gmail-mcp auth --scopes=gmail.readonly

# Read + send (mailing-list bot)
npx @klodr/gmail-mcp auth --scopes=gmail.readonly,gmail.send

# Everything (default; explicit)
npx @klodr/gmail-mcp auth --scopes=gmail.modify,gmail.settings.basic

# Default + permanent delete (delete_email / batch_delete_emails)
# gmail.modify authorizes trash; mail.google.com is the only scope
# that authorizes purging from Trash. Both are listed because the
# tool gate does exact scope-name matching — a token holding only
# mail.google.com would not enable the gmail.modify-gated tools,
# even though Google's scope hierarchy would technically accept the
# same calls.
npx @klodr/gmail-mcp auth --scopes=gmail.modify,mail.google.com,gmail.settings.basic

🛡️ 安全対策

プロセス内ミドルウェア（自律性の適用）

自律型 LLM クライアントが違反できない実行時制約は、オペレーターの注意力に頼るのではなく、サーバー内で適用されます。プロセス内の7つのモジュールがツールのエントリーパスに配置されており、オプトイン方式のモジュールは、対応する環境変数が設定された場合にのみ有効になります。

常時有効（デフォルトですべての呼び出しで有効）：

• sanitize.ts — LLM が提供する入力から、Gmail のヘッダー、ファイル名、ファイルシステムのパスに渡る前に、CRLF インジェクション、制御文字、NUL バイトを除去またはエスケープします。
• sender-resolver.ts — 送信元として使用できるアドレスのリストを読み取れ、空でない場合、from パラメーターをアカウントで許可された送信元エイリアスだけと照合して解決します。そのため、送信者フィールドの偽装は Gmail API の送信呼び出し前に拒否されます。リストを利用できない、または空の場合、明示的に指定された from は変更せずにそのまま渡されます。from が指定されておらず、送信元リストを読み取れる場合、返信、転送、スレッド内の send_email／draft_email では、Gmail のウェブ UI と同様に、会話ですでに使用されているエイリアス（元のメッセージの送信元または宛先のエイリアス、それ以外はスレッドで最後に使われたエイリアス）が使用されます。また、reply_all でアカウントのエイリアスがコピーされることはありません。リストを利用できない場合（たとえば、gmail.send または gmail.compose に制限されたトークンの場合）、送信元は resolveDefaultSender にフォールバックし、reply_all ではアカウント自身のアドレスのみが除外されます。
• rate-limit.ts — ローリング方式の日次／月次期間における、ツールファミリー（send、delete、modify、drafts、labels、filters、pairing）ごとの書き込み量を制限します。バッチツール（batch_modify_emails、batch_delete_emails、move_to_spam_batch）では、処理するメッセージごとにカウントされるため、1,000 件のメッセージに対する 1 回の呼び出しでは 1 単位ではなく 1,000 単位を使用します。状態はディスクに保存され、再起動後も維持されます。テスト実行時のみ、GMAIL_MCP_RATE_LIMIT_DISABLE=true` で無効にできます。
• quarantine.ts — download_attachment、download_all_attachments、download_email によって書き込まれるすべてのファイルに、Mail や Outlook と同様に、インターネットからダウンロードされたことを示すマークを付けます。macOS では com.apple.quarantine 属性（実行ファイルやスクリプトを開くときに Gatekeeper が確認します）、Windows では Mark of the Web を付けます。Linux では何もしません。処理を妨げることはありません。マークを設定できなくても、ファイルは保存されます。GMAIL_MCP_QUARANTINE=false で無効にできます。
• 転送フィルターの拒否（filter-manager.ts） — create_filter とフィルターテンプレートでは、メールを転送するルールを設定しません。このようなルールは今後一致するすべてのメッセージを気付かれないまま転送し、Gmail で転送するには確認済みの転送先アドレスが必要です。その登録には gmail.settings.sharing スコープが必要ですが、これはデフォルトのスコープに含まれず、ここにあるツールでも使用されません。--scopes でこのスコープを許可しても、拒否は適用されます。転送ルールは Gmail のウェブインターフェースで作成してください。
• エクスポートされる HTML（email-export.ts） — download_email が html 形式で書き込むファイルには、スクリプト、プラグイン、フレーム、<base> による書き換え、フォーム送信、およびデフォルトですべてのリモート取得（画像、スタイルシート、フォント、メディアなど。default-src 'none'）をブロックする Content-Security-Policy が設定されます。そのため、トラッキングピクセルやスタイルシートから、コピーを開いた日時や場所が報告されることはありません（インラインスタイルと画像は引き続き表示されます）。送信者の <meta http-equiv="refresh"> は無効化されます。呼び出しごとに allowRemoteImages: true を指定するか、GMAIL_MCP_EXPORT_REMOTE_IMAGES=true を設定すると、リモートコンテンツを許可できます。
• send_draft の宛先チェック — 送信前に下書きの内容を読み取り、To／Cc／Bcc ヘッダーをアドレスのリストとして解析できない場合は拒否します。そのため、下書きの宛先は必ず確認できます。
• gmail-errors.ts — Gmail API のさまざまな失敗を型付きエラーに正規化し、再試行や LLM へのエラー通知が一貫して行われるようにします。
• middleware.ts — 常時有効な処理チェーンを組み立て、すべてのツールのエントリーポイントに適用します。新しいツールには、このパイプラインが自動的に適用されます。

オプトイン（デフォルトでは無効です。有効にするには環境変数を設定してください）：

• recipient-pairing.ts — オペレーターが管理する許可リスト（~/.gmail-mcp/paired.json）にないアドレスへのメール送信を拒否します。幻覚によるアドレス宛てに、新たな送信先へメールが送られることはありません。GMAIL_MCP_RECIPIENT_PAIRING=true の場合に有効になり、send_email／reply_*／forward_email／draft_email／update_draft／send_draft の各ツールを制限します。アドレスは名前を除いた値で比較されます（Name <address> はペア登録済みの address と一致します）。制限が有効な間、モデルは gmail-mcp を通じてリストを拡張できません。pair_recipient add は、MCP クライアントを通じて人間に確認を求め（エリシテーション）、クライアントが確認を求められない場合は拒否し、ターミナルコマンド npx @klodr/gmail-mcp pair add <address>（pair remove、pair list も同様）を案内します。そうしなければ、悪意のあるメールによってエージェントが自身のアドレスをペア登録し、そのアドレスにメールを送信してしまう可能性があります。この保証が及ぶのは gmail-mcp の範囲です。MCP クライアントがモデルにターミナルコマンド（npx @klodr/gmail-mcp pair add など）の実行や、承認なしでの paired.json への書き込みも許可しない限り、保証は維持されます。
• audit-log.ts — すべてのツール呼び出し（名前、編集済みの引数、結果）を追記専用の JSONL 記録として残し、構造上のキーを保持したまま編集することで、オペレーターが事後に判断を再現できるようにします。GMAIL_MCP_AUDIT_LOG=/abs/path/audit.jsonl が設定されている場合に有効になります。

以下の環境変数を使用して各モジュールを設定します。

設定項目	環境変数	デフォルト	備考
添付ファイルの隔離ディレクトリ	GMAIL_MCP_ATTACHMENT_DIR=/abs/path	~/GmailAttachments/（モード 0o700 で自動作成）	すべての添付ファイルのパス（send_email、draft_email、update_draft、reply_all、reply_to_email、forward_email）は、realpath による正規化後にこのディレクトリ内に存在する必要があります。外部を指すシンボリックリンクは拒否されます。プロンプトインジェクションによる ~/.ssh/id_rsa、~/.gmail-mcp/credentials.json、~/.claude.json などの流出を防ぎます。
ダウンロードの隔離ディレクトリ	GMAIL_MCP_DOWNLOAD_DIR=/abs/path	~/GmailDownloads/（モード 0o700 で自動作成）	download_email、download_attachment、download_all_attachments は、ファイルと ZIP のいずれもこの場所にのみ書き込みます。末端のファイルは O_NOFOLLOW で開き、mkdir 後に解決済みのパスが隔離ルート内にあることを再検証します（TOCTOU 対策）。
OAuth キーのパス	GMAIL_OAUTH_PATH=/abs/path/gcp-oauth.keys.json	~/.gmail-mcp/gcp-oauth.keys.json	Google Desktop/Web OAuth クライアントの認証情報です。
認証情報のパス	GMAIL_CREDENTIALS_PATH=/abs/path/credentials.json	~/.gmail-mcp/credentials.json	アクセストークンとリフレッシュトークンです。ファイルモードは 0o600 です。
レート制限状態ディレクトリ	GMAIL_MCP_STATE_DIR=/abs/path	~/.gmail-mcp/	レート制限用のローリング呼び出し履歴（ratelimit.json、モード 0o600）の保存先です。今後の状態ファイルにも同じディレクトリを使用します。
レート制限の上書き設定	GMAIL_MCP_RATE_LIMIT_<bucket>=D/day,M/month	下記を参照	バケットごとの日次／月次上限を上書きします。バケット：send（100/2000）、delete（1000/10000）、modify（5000/50000）、drafts（300/3000）、labels（50/500）、filters（20/200）、pairing（50/500）。バッチツールでは delete と modify はメッセージ数でカウントされます。1 日 5,000 件の変更で、1,000 件のメッセージを対象とするバッチを 5 回（受信トレイの大規模な整理に相当）実行でき、暴走するループも停止できます。完全削除は引き続き 1 日 1,000 件に制限されます。すべての送信系ツール（send_email、reply_all、reply_to_email、forward_email、send_draft）は send バケットを共有します。send の上限は、専門職の人間の業務量の上限（1 日あたり約 40 通）に 2.5 倍の余裕を持たせて設定されています。v0.30.2 より前のデフォルト値が必要な場合は、GMAIL_MCP_RATE_LIMIT_send=400/day,6000/month で引き上げてください。バケット名は小文字で、ツールの種類に対応します。
レート制限の無効化	GMAIL_MCP_RATE_LIMIT_DISABLE=true	未設定（リミッターは有効）	リミッター全体の緊急停止スイッチです。テストスイートまたは管理されたバッチ処理でのみ使用してください。
受信者のペアリング	GMAIL_MCP_RECIPIENT_PAIRING=true	未設定（許可リストなし）	ペアリング済みのアドレス（GMAIL_MCP_PAIRED_PATH、デフォルトは ~/.gmail-mcp/paired.json）にのみ送信します。ターミナルで npx @klodr/gmail-mcp pair add <address> を実行するか、確認を求める pair_recipient を使用してペアリングします。
ペアリング確認の待機時間	GMAIL_MCP_PAIRING_CONFIRM_TIMEOUT_MS=600000	10 分	pair_recipient add が確認フォームへの回答を待つ時間です。時間切れになると中止され（ペアリングは行われません）。ミリ秒単位の正の整数を指定してください。それ以外の値ではデフォルト値に戻ります。MCP クライアント独自のツール呼び出しタイムアウトにより、これより早く待機が終了する場合があります。
ダウンロードの隔離属性	GMAIL_MCP_QUARANTINE=false	有効	ダウンロードしたすべてのファイルに macOS の com.apple.quarantine／Windows の Mark of the Web を付与します。Linux では何も行いません。ダウンロードがブロックされることはありません。
エクスポートした HTML 内のリモートコンテンツ（画像、スタイルシート、フォント、メディア）	GMAIL_MCP_EXPORT_REMOTE_IMAGES=true	ブロック	html 形式の download_email におけるデフォルト設定です。呼び出しごとの allowRemoteImages が優先されます。
監査ログ	GMAIL_MCP_AUDIT_LOG=/abs/path/audit.jsonl	未設定（監査記録なし）	すべてのツール呼び出し（名前、機密情報を除去した引数、結果）を記録する、オプトイン方式の追記専用 JSONL ログです。ファイルモードは 0o600 です。絶対パスを指定する必要があり、相対パスは起動時に拒否されます。構造を示すキーは保持し、許可リストに含まれる値は除去します。
ドライラン	GMAIL_MCP_DRY_RUN=true	未設定（実際に呼び出す）	"true" と厳密に一致する場合、すべての書き込みツール（send_email、reply_all、reply_to_email、forward_email、draft_email、update_draft、delete_draft、send_draft、delete_email、modify_email、batch_modify_emails、move_to_spam、move_to_spam_batch、batch_delete_emails、create_label、update_label、delete_label、get_or_create_label、create_filter、delete_filter、create_filter_from_template、modify_thread、pair_recipient）は Gmail に到達する前に処理を早期終了し、送信されるはずだったペイロードを機密情報の除去後に返します。対象となるのは、レート制限のあるツールとまったく同じ範囲です。pair_recipient は list を含むすべてのアクションで早期終了します。CI のスモークテスト、エージェントのデバッグ、人間が介在する承認ワークフローに便利です。読み取りツールとローカルのみで動作する download_* ツールはこのフラグを無視します（メールボックス内にプレビューするものがないためです）。関連サーバーの MERCURY_MCP_DRY_RUN／FAXDROP_MCP_DRY_RUN と同じ動作です。

🛠️ ツール

正確なセットは、auth 時に付与される OAuth スコープによって異なります。全カタログ：

• メッセージ — send_email、draft_email、read_email、search_emails、modify_email、delete_email、download_email、download_attachment、download_all_attachments、batch_modify_emails、batch_delete_emails、reply_all、reply_to_email、forward_email
• 下書き — list_drafts、get_draft、update_draft、delete_draft、send_draft（users.drafts.* の全機能。上記の draft_email は最初の下書きを作成します）
• スレッド — get_thread、list_inbox_threads、get_inbox_with_threads、modify_thread
• ラベル — list_email_labels、create_label、update_label、delete_label、get_or_create_label
• フィルター — list_filters、get_filter、create_filter、delete_filter、create_filter_from_template
• 受信者のペアリング — pair_recipient（GMAIL_MCP_RECIPIENT_PAIRING=true の場合に、~/.gmail-mcp/paired.json の許可リストを管理します）

すべての書き込みツールには、MCP の仕様に従って destructiveHint／readOnlyHint／idempotentHint が付与されているため、ポリシーを認識するクライアントは HITL 確認の要否を判断できます。

🔍 search_emails のクエリ構文

search_emails は Gmail のネイティブ検索演算子（from:、to:、subject:、has:attachment、after:YYYY/MM/DD、before:YYYY/MM/DD、is:unread、label:<name> など）を受け付けます。これらは自由に組み合わせられます。例：from:alice after:2026/01/01 has:attachment。詳しくは、Google の Gmail 検索演算子チートシートをご覧ください。クエリに一致するものがない場合、空の結果ではなく No messages found for query: <query> が返されます。

🗺️ ロードマップ

ROADMAP.md をご覧ください。

🌐 エコシステム

klodr ファミリーのその他の MCP サーバー

• 📧 klodr/gmail-mcp — Gmail（現在ご覧のプロジェクトです）
• 📠 klodr/faxdrop-mcp — FaxDrop 経由で実際のファクスを送信
• 🏦 klodr/mercury-invoicing-mcp — Mercury の銀行業務と請求書発行

Gmail-MCP のより広いエコシステム

単独のリポジトリ 29 件と、元の GongRzhe サーバーのフォーク 349 件を docs/COMPETITORS.md でレビューしています。採用したアイデア、採用しなかったアイデア、および成熟度の各軸における klodr/gmail-mcp の位置づけをまとめています。

🤝 貢献

テスト／ビルド／リントのチェックリストとリリースプロセスについては、CONTRIBUTING.md をご覧ください。

🔒 セキュリティ

脆弱性の報告手順と現在のセキュリティモデルについては SECURITY.md を、脅威モデル、信頼境界、CWE／OWASP の緩和策一覧については ASSURANCE_CASE.md をご覧ください。

📋 プロジェクトの継続性

メンテナーが対応できなくなった場合の引き継ぎ計画については、CONTINUITY.md をご覧ください。

📄 ライセンス

MIT — LICENSE をご覧ください。

📜 履歴

klodr/gmail-mcp は、2 段階の上流チェーンを引き継いだメンテナンスフォークです。

• GongRzhe/Gmail-MCP-Server — 元のサーバーです。2025 年 8 月以降メンテナンスされておらず（メンテナーの活動が 7 か月以上なく、未マージのプルリクエストが 72 件以上あります）。
• ArtyMcLabin/Gmail-MCP-Server — Arty MacKiewicz による活発なフォークです。Gong から分岐して以来、コミュニティからの貢献として、全員に返信（#3、@MaxGhenis による）、list_filters の修正（#4、@nicholas-anthony-ai による）、CI/CD のシェルインジェクション対策の強化（#9、@JF10R による）、download_email（#13、@icanhasjonas による）、ツールアノテーション（#14、@bryankthompson による）、read_email の CC/BCC フィールド（#21、@panghy による）、および下書きのライフサイクルツール send_draft / delete_draft / update_draft（#30、@thisisambros による）がマージされました。返信スレッドの自動解決と --scopes フラグは、メンテナーによって直接取り込まれました。

klodr/gmail-mcp は上記のすべてを引き継ぎ、サプライチェーン／パス制限／レビュー方針のレイヤーを追加しています（上記の比較表を参照）。チェーンに加わったすべての PR 作成者に感謝します。