gmail-tidy-mcp

gmail-tidy-mcp

複数の Gmail アカウントを一度に検索、閲覧、ラベル付け、アーカイブし、フィルターを設定して下書きを作成できる MCP サーバーです。

メールの送信や削除はできません。「先に確認を求める」ということではありません。そもそもそのためのツールがなく、送信または削除の呼び出しがコードに追加されると、テストでビルドが失敗します。

理由

多くの Gmail MCP サーバーは、メールの送信も含めてモデルにメールボックスの完全な操作権限を与え、OAuth トークンをディスク上にプレーンテキストで保存します。見知らぬ人が書いたメールも読むモデルに、これほどの信頼を置くことになります。

このサーバーが掲げる約束は、より限定的です。アシスタントは受信トレイの整理を手伝えますが、何かを送信したり削除したりすることはできません。

できること

分野	ツール
アカウント	list_accounts、check_accounts、connect_account、finish_connect_account
閲覧	search_emails（Gmail 検索構文）、search_all_accounts（すべてのアカウントを一度に検索）、get_email（添付ファイルを一覧表示）、get_thread（会話全体を古い順に表示し、引用履歴を短縮）、get_attachment（テキスト、.gz、.zip はインラインで読み込み。例：DMARC レポート。PDF など、それ以外のファイルは ~/Downloads/gmail-tidy-mcp に保存）、sender_stats（アドレスとドメイン別に、送信数の多い相手を表示）、newsletters（配信量順にメーリングリストを表示し、各リストが示す配信停止リンクも表示。代わりに配信停止することはありません）
ラベル	list_labels、create_label（Parent/Child の形式で階層化）、update_label（名前の変更、Gmail のパレットでの色変更、サイドバーでの表示・非表示）
整理	organize_emails：ID または検索条件でラベルを追加・削除。一度に最大 5,000 件のメッセージを処理できます。アーカイブは INBOX の削除、既読にする操作は UNREAD の削除です
フィルター	list_filters、create_filter、delete_filter。受信トレイをスキップするフィルターには、明示的に skip_inbox: true を指定する必要があります
下書き	create_draft。スレッド内での返信や、ローカルファイルの添付も任意で指定できます。list_drafts。update_draft は既存の下書きを編集します（指定したフィールドのみ変更され、スレッドと現在の添付ファイルはそのままです）。送信は Gmail から自分で行います
設定	set_signature：署名のみを変更し、メールの送信方法は変更しません
監査	recent_changes：このサーバーが行ったすべての変更を確認し、セッションを元に戻すための機能です

各アカウントには短いラベルが付くため、「work で 1 か月以上前のニュースレターをすべてアーカイブして」のように指示できます。

できないこと

• メールの送信、返信、転送、削除や、ゴミ箱または迷惑メールへの移動。
• これらを後から追加する手段をモデルに与えること。ツールはコードで固定されており、モデルは任意の Gmail エンドポイントを呼び出せません。

Google には、送信は許可せずに下書きだけを許可するスコープがないため、このサーバーは gmail.modify（技術上は送信も可能）と、フィルター用の gmail.settings.basic を要求します。この保証はコードによるもので、test/safety.test.js が実行のたびに確認します。

セキュリティ

• トークンは暗号化されます。 AES-256-GCM を使用して ~/.config/gmail-tidy-mcp/tokens.enc（モード 600）に保存されます。キーは macOS Keychain、Linux Secret Service（secret-tool）、または Windows の DPAPI で保護されたファイルに保存されます。GMAIL_TIDY_KEY（64 桁の 16 進数）を使って、自分で指定することもできます。
• サインインには PKCE とランダムな state を使用し、リダイレクト先は 127.0.0.1 のみに限定されます。
• サインインしたアカウントを検証します。 サインイン後、サーバーは Gmail に取得したアドレスを問い合わせます。それが指定したアドレスと異なる場合、または Google が異なるスコープを付与した場合、トークンは取り消され、何も保存されません。
• OAuth クライアントはご自身のものを使用します。 共有クライアントもサードパーティのサーバーもありません。メールは Google からご利用のマシンに届き、それ以外の場所には送信されません。
• メールの内容は信頼できないデータとして隔離されます。 Gmail から読み取ったものはすべて、呼び出しごとにランダムな値を含むマーカーで囲まれたブロックに入ります。そのため、メールがブロックを早期に閉じることはできません。ヘッダー内の制御文字は削除され、HTML は表示テキストに変換されます（スクリプト、スタイル、display:none、visibility:hidden、font-size:0、opacity:0 で隠されたテキストは削除されます）。
• 不可視テキストは削除されます。 モデルには読めても人には見えない指示の埋め込みに使われる Unicode タグ文字、ゼロ幅文字、テキスト方向制御文字は、ヘッダー、本文、添付ファイルから取り除かれます。タグ文字にはメールで正当な用途がないため、検出されたことが報告されます。
• セキュリティに関する通知は、送信者ではなくサーバーが生成します。 get_email と get_attachment は、信頼できないブロックの上に検出内容を簡潔に表示します。検出内容には、プロンプトインジェクションでよく使われる表現、SPF、DKIM、DMARC の検証失敗、送信者が DMARC に合格していない場合に返信先が無料のウェブメールアドレスになっていること、別のアドレスを装った表示名、表示されているサイトと実際のリンク先が異なるリンクが含まれます（Gmail と Outlook のリダイレクト用ラッパーは事前に解除され、メーリングリストのトラッキングリンクは警告対象になりません）。通常のメールでは通知が出ないよう調整されているため、通知がある場合は注意が必要です。
• 類似した送信者には警告が表示されます。 ドメイン名が接続済みアカウントのいずれかと 1 文字または 2 文字しか違わない送信者、またはラテン文字に似た他の文字体系の文字を使用する送信者には通知が表示されます。Gmail などのウェブメールでは、代わりにメールボックス名を比較します。ご自身のアカウント間のメールには警告が表示されません。
• 下書きに添付できるのは、ユーザーフォルダー内のファイルのみです。 添付ファイルは Downloads、Desktop、Documents、または GMAIL_TIDY_ATTACH_DIRS 内のフォルダーに置く必要があります。隠しフォルダー内のファイルや、このサーバー自身の設定ファイルは添付できません。確認前にリンクを解決するため、ショートカットを使って ~/.ssh を参照することもできません。これにより、悪意あるメールに誘導されたモデルが、秘密鍵やトークンを下書きに忍び込ませて送信させることを防ぎます。
• 変更はすべてローカルに記録されます。 ラベル、アーカイブ、フィルター、下書き、署名の変更、保存したファイルは、メッセージ本文、下書きのテキスト、署名そのものを含めずに ~/.config/gmail-tidy-mcp/audit.log（モード 600）に追記されます。recent_changes で記録を確認できるため、セッション中に不審な操作があった場合に、何が起きたかを正確に把握し、元に戻すことができます。
• 危険な添付ファイルは保存されません。 実行ファイルやスクリプト、偽装された名前（factura.pdf.exe、右書き文字による偽装など）、拡張子と実際のバイトデータが一致しないファイル、およびそのようなファイルを含むアーカイブは、呼び出しで allow_risky: true が指定されていない限り拒否されます。パスワード保護されたアーカイブ、マクロ有効の Office ファイル、JavaScript または自動実行アクションを含む PDF には警告が表示されます。保存したファイルが既存のファイルを上書きすることはなく、ダウンロードフォルダー外に書き込むこともできません。また、macOS では隔離フラグが付けられるため、開く前に Gatekeeper がチェックします。
• 下書きにヘッダーを紛れ込ませることはできません。 To、Cc、Subject、返信ヘッダー内の改行は拒否されるため、隠し Bcc を挿入することはできません。
• 引数は Gmail に渡される前に検証されます。 また、変更を行うツールには MCP アノテーション（destructiveHint）が付いているため、クライアントは実行前にユーザーに確認できます。
• 大量のスキャンでは Gmail の割り当て上限が考慮されます。 sender_stats、newsletters、検索では一度に少数のメッセージを取得し、Gmail から要求された場合は処理を遅らせます。そのため、大きなメールボックスではスキャンが遅くなるだけで、処理が中断されることはありません。
• ランタイム依存関係は 2 つ（@modelcontextprotocol/sdk と googleapis）で、どちらも厳密なバージョンに固定されており、インストールスクリプトは含まれていません。

それでも起こりうること

どのサーバーでもプロンプトインジェクションを完全に防ぐことはできません。また、セキュリティに関する注意事項はヒューリスティックであり、よくある手口は検出できますが、すべてを検出できるわけではなく、問題が見つからなかったからといって安全が証明されるわけではありません。悪意のあるメールによってモデルがだまされた場合、次のような操作が行われる可能性があります。

• メールに別のラベルを付けたり、アーカイブしたりする（元に戻せます）。
• 受信トレイに新着メールが表示されないようにするフィルターを作成する（skip_inbox: true の場合に限られ、クライアントから事前に確認することもできます）。
• フィルターを削除する（フィルターは復元できません）。
• 誤解を招く下書きを作成する。あなたが送信しない限り、送信されることはありません。
• ラベル名や色を変更したり、署名を変更したり、下書きを書き換えたりする（すべて元に戻せます。監査ログには変更内容が記録されます）。
• 危険と判定された添付ファイルを保存する（allow_risky: true も設定されている場合）。開くかどうかは、引き続きあなたの判断です。

知っておくとよいことが、あと2つあります。

• トークン自体でメールを送信できます。「メールを送信しない」という保証はトークンではなく、このコードによるものです。誰かにトークンとキーの両方を盗まれると、gmail.modify で許可されている操作を実行される可能性があります。マシンとキーチェーンを安全に保ってください。
• **macOS では、キーチェーンの項目が /usr/bin/security を信頼します。**つまり、あなたとして実行されているプロセスは、プロンプトなしでキーを読み取れます。これによってキーをディスクに保存せずに済みますが、あなたのユーザー権限で動作するマルウェアを防ぐものではありません。

セットアップ

Node.js 22 以降が必要です。

1. Google OAuth クライアントを作成する（一度だけ）

1. Google Cloud Console でプロジェクトを作成し、Gmail API を有効にします。
2. Google Auth Platform でアプリを External として設定し、サポート用および連絡先用のメールアドレスとして自分のメールアドレスを追加して、公開します（Audience → Publish app）。本番環境の未確認アプリでは、リフレッシュトークンは保持されます。テストモードでは、7 日後に期限切れになります。
3. Clients で、種類が Desktop app のクライアントを作成し、JSON をダウンロードします。
4. ~/.config/gmail-tidy-mcp/oauth-client.json として保存し、アクセスを制限します（macOS と Linux では chmod 600 を実行します）。

アカウントを接続すると、Google からアプリが未確認であることを示す警告が表示されます。これは想定どおりです。アプリはあなた自身のものです。Advanced を選んで続行してください。

2. MCP クライアントに登録する

Claude Code：

claude mcp add -s user gmail-tidy -- npx -y gmail-tidy-mcp

その他の MCP クライアント：npx -y gmail-tidy-mcp を stdio 経由で実行します。

ソースから実行する場合は、リポジトリをクローンし、npm ci --ignore-scripts を実行してから、クライアントの実行先として node /path/to/gmail-tidy-mcp/bin/gmail-tidy-mcp.js を指定します。

Linux では、キーをキーチェーンに保存できるよう、まず libsecret-tools をインストールしてください。

3. アカウントを接続する

アカウントを接続するようアシスタントに依頼します。ブラウザーで Google のログインページが開きます。ターミナルから接続することもできます。

npx gmail-tidy-mcp add [email protected] personal
npx gmail-tidy-mcp list
npx gmail-tidy-mcp remove [email protected]

アカウントを削除すると、トークンがローカルから削除されます。Google 側でもアクセスを取り消すには、myaccount.google.com/permissions にアクセスしてください。

Google Workspace アカウントでは、未確認アプリを許可するよう管理者に依頼する必要がある場合があります。

開発

npm test

テストでは、安全性の保証（送信や削除の呼び出しがないこと、ゴミ箱や迷惑メールを使用しないこと、フィルターの操作がラベルに限定されること）、トークンの暗号化とキーの処理、サインインのコールバック（state、エラー、タイムアウト）、ログイン後の確認、下書きのヘッダーと本文のデコードを検証します。CI では Linux、macOS、Windows 上でテストを実行し、Windows では実際の DPAPI 経路も含めて検証します。

クレジット

このプロジェクトは、Rogers Xie による gx-55/multi-gmail-mcp（MIT）から始まりました。その基盤の一部は今も使用しています。ラベルまたはアドレスによるアカウント検索、メッセージ検索とヘッダーのヘルパー、返信のスレッド化、トークンエラーの検出です。ストレージ、サインインフロー、ツールセット、安全モデルは再設計しました。

ライセンス

MIT です。LICENSE を参照してください。