Gmail Cleanup MCP Server

Gmail インボックス整理に特化した Model Context Protocol サーバー — メールのゴミ箱移動、フィルタ管理、配信停止リンクの抽出を行います。読み取り・検索・下書き・送信を担当する Anthropic 組み込みの Gmail コネクタを補完するように設計されています。

dcerniglia/gmail-cleanup-mcp（MIT ライセンス）のパッチ適用フォークです。このフォークは、search_and_trash と batch_trash_emails が失敗を黙って見逃してリトライしなかったバグを修正しています — 50 件の同時ゴミ箱移動リクエストを発火すると Gmail のレート制限に抵触し、バッチの約半数がエラー表示なしで失われる可能性がありました。現在は両ツールともバッチサイズを小さくし、バックオフ、自動リトライを行い、失敗したメッセージごとに実際のエラーを報告します。

ツール

Related MCP server: Gmail AutoAuth MCP Server

前提条件

• Node.js 18+

• Gmail API が有効な Google Cloud プロジェクト

• OAuth 2.0 認証情報（デスクトップアプリタイプ）

セットアップ

1. Google Cloud OAuth

別の Gmail MCP サーバーで ~/.gmail-mcp/gcp-oauth.keys.json をすでにお持ちですか？手順 2 に進んでください — このサーバーは同じ認証情報の場所を使用します。

1. Google Cloud Console に移動

2. プロジェクトを作成（または既存のものを再利用）し、Gmail API を有効化

3. 認証情報 → 認証情報を作成 → OAuth クライアント ID に移動

4. デスクトップアプリを選択し、JSON をダウンロード

5. ~/.gmail-mcp/gcp-oauth.keys.json として保存（またはプロジェクトディレクトリに gcp-oauth.keys.json を配置 — 初回実行時に自動的にコピーされます）

2. インストールとビルド

git clone https://github.com/davidcerniglia/gmail-cleanup-mcp.git
cd gmail-cleanup-mcp
npm install
npm run build

3. 認証

npm run auth

Google OAuth の同意画面がブラウザで開きます。認証情報は 0600 パーミッション（所有者のみ）で ~/.gmail-mcp/credentials.json に保存されます。

4. Claude Desktop に追加

macOS の ~/Library/Application Support/Claude/claude_desktop_config.json に追加:

{
  "mcpServers": {
    "gmail-cleanup": {
      "command": "node",
      "args": ["/absolute/path/to/gmail-cleanup-mcp/dist/index.js"]
    }
  }
}

または Claude Code の場合は、.claude/settings.json に追加:

{
  "mcpServers": {
    "gmail-cleanup": {
      "command": "node",
      "args": ["/absolute/path/to/gmail-cleanup-mcp/dist/index.js"]
    }
  }
}

使用例

Claude 組み込みの Gmail との連携

セキュリティ

• 最小スコープ: gmail.modify + gmail.settings.basic — ゴミ箱移動とフィルタ操作に必要な最小限

• 削除ではなくゴミ箱移動: すべての削除は Gmail のゴミ箱（30 日間の復元期間）を使用し、完全削除は行いません

• ドライランモード: search_and_trash は実行前に一致をプレビュー可能

• 制限的なファイルパーミッション: 認証情報は 0600（所有者のみ読み書き）で保存

• 添付ファイルの処理なし: パストラバーサルのリスクゼロ

• ~/.gmail-mcp/ の認証情報保存以外のファイルシステムアクセスなし

環境変数

ライセンス

MIT