Gmail MCP Server

Gmail MCP サーバー（積極的にメンテナンスされているフォーク）

インストール： npx @artymclabin/gmail-mcp auth — または、Claude にこのリポジトリ（https://github.com/ArtyMcLabin/Gmail-MCP-Server）から MCP をインストールするよう伝えて、セットアップを任せてください。手動での手順をご希望ですか？インストールと認証をご覧ください。

公式 MCP Registry（io.github.ArtyMcLabin/Gmail-MCP-Server）および Smitheryにも掲載されています。

これは GongRzhe/Gmail-MCP-Server の、積極的にメンテナンスされているフォークです。

元のリポジトリは2025年8月以降メンテナンスされておらず、メンテナーの活動が7か月以上なく、72件以上のプルリクエストが未マージのままです。私は Claude Code のワークフローの一環としてこの MCP サーバーを毎日使っており、正しく動作することが欠かせないため、引き継ぎました。

プルリクエストを歓迎します。 修正や機能を用意していたものの、投稿先がなかった方は、ぜひこちらにお寄せください。

開発方針

このフォークは軽量で実用的です。ローカルで動作する stdio MCP サーバーであり、ご自身のマシンで実行します。また、LLM クライアントにはすでにシェルとファイルシステムへのアクセスがあります。そのため、脅威モデルは「サードパーティに認証情報を漏らさないこと、Gmail の機能を壊さないこと」であり、「ホスト型のマルチテナントサービスを防御すること」ではありません。依存関係は最小限に抑えています。自分の Claude Code のワークフローで毎日使っています。自分で実行したりメンテナンスしたりしないものは、取り入れません。

この方針を最大限に追求した下流フォークがあります。私はそのメンテナーとは関係がなく、セキュリティや機能の状況も追っていません。ご自身の責任でご利用ください：klodr/gmail-mcp。その方針がお望みなら、ぜひご覧ください。こちらではいつでもプルリクエストを歓迎します。

このフォークで追加されたもの

• 返信スレッドの修正 - In-Reply-To および References ヘッダーを自動的に解決し、メールの返信が孤立したメッセージを作成せず、正しいスレッドに届くようにします（upstream PR #91、引き続き対応待ち）
• 送信元エイリアスのサポート - 複数の ID でメールを管理するための任意の from パラメーター（設定済みの Gmail エイリアスから送信できます）
• 全員に返信するツール - reply_all は元のメールを自動的に取得し、自分を除外した To/CC 受信者リストを作成して、適切なスレッドヘッダーを設定します（@MaxGhenis による PR #3）
• list_filters の修正 - レスポンスのプロパティ名が誤っていたため、空の配列を返していました（@nicholas-anthony-ai による PR #4）
• カスタム OAuth2 スコープ設定 - --scopes フラグで必要な権限のみをリクエストし、ツールを自動的にフィルタリングします（@tansanDOTeth による PR #6）
• CI/CD の強化 - GitHub Actions ワークフローのシェルインジェクションの脆弱性を修正し、最小権限の権限スコープを追加しました（@JF10R による PR #9）
• セキュリティの強化 - 添付ファイルのダウンロードにおけるパストラバーサルを修正し、OAuth 認証情報ファイルの権限を制限しました（@JF10R による PR #10）
• 依存関係のセキュリティ - MCP SDK を v1.27.1 にアップグレード（CVE 修正 3 件）、nodemailer をアップグレード（DoS とルーティングの修正）、開発専用パッケージを本番環境の依存関係から分離しました（@JF10R による PR #11）
• スレッドレベルのツール - get_thread、list_inbox_threads、get_inbox_with_threads、modify_thread を使い、1 回の呼び出しでスレッド単位のメール操作を効率的に行えます
• CC/BCC の表示 - CC と BCC のヘッダーが存在する場合、read_email に表示されるようになりました（@panghy による PR #21）
• フィッシング報告ツール - Gmail API を通じてメッセージを迷惑メールとしてマークする report_phishing と batch_report_phishing を追加しました（@ShivamB25 による PR #24）
• 下書きライフサイクルツール - send_draft、delete_draft、update_draft により、孤立した下書きの問題を解消します。send_draft は既存の下書きをアトミックに送信して下書きから削除するため、残骸が残りません。update_draft は ID を保持したまま下書きをその場で変更するため、反復処理のたびに下書きが増えません。delete_draft は放棄した下書きを破棄します（@thisisambros による PR #30）
• ツールのアノテーション - すべてのツールに MCP 仕様のアノテーション（readOnlyHint、destructiveHint、idempotentHint）を追加し、LLM によるツール実行の安全性を高めました（@bryankthompson による PR #14）
• メールのダウンロードツール - download_email は、LLM のコンテキストを消費せずにメールを json/eml/txt/html 形式でディスクに保存します（@icanhasjonas による PR #13）
• 永続的な OAuth セッション - refresh_token が再起動後も保持されるため、毎時の再認証ループが解消されます（@BrentBaccala による PR #35）
• OAuth コールバックポートのカスタマイズ - 認証リスナーはポート 3000 をハードコードせず、コールバック URL からポートとパスを取得します（@soapergem による PR #41）
• 完全削除の安全な制御 - delete_email／batch_delete_emails にはオプトインの gmail.full スコープが必要です（このスコープは他のすべてのメールスコープも満たします）。そのため、デフォルトの認証では最小権限が維持されます（@caioribeiroclw-pixel による PR #39） すべての機能は、日常的な使用で本番環境のテストを実施済みです。

---

Claude Desktop での Gmail 連携に対応し、自動認証をサポートする Model Context Protocol（MCP）サーバーです。このサーバーを使用すると、AI アシスタントが自然言語で Gmail を操作できます。

機能

• 件名、本文、添付ファイル、宛先を指定してメールを送信
• 添付ファイルを完全サポート — ファイルの添付と受信に対応
• メールの添付ファイルをローカルファイルシステムにダウンロード
• メール全体を json/eml/txt/html 形式のファイルにダウンロード
• スレッド単位の操作 — スレッド全体の取得、受信トレイのスレッド一覧表示、複数スレッドの一括展開
• HTML メールと、HTML 版およびプレーンテキスト版の両方を含むマルチパートメッセージに対応
• 件名とメール本文で国際文字を完全サポート
• 高度な MIME 構造処理による、ID を指定したメールメッセージの読み取り
• ファイル名、種類、サイズ、ダウンロード ID を表示する、強化された添付ファイル表示
• 件名、送信者、日付範囲などの条件でメールを検索
• ラベルの作成、更新、削除、一覧表示に対応する包括的なラベル管理
• 利用可能なすべての Gmail ラベル（システム定義およびユーザー定義）を一覧表示
• 受信トレイ、送信済み、またはカスタムラベル内のメールを一覧表示
• メールを既読または未読に設定
• メールを別のラベル／フォルダーに移動
• メールを削除
• 複数のメールを一度に効率よく処理する一括操作
• Gmail API との完全な連携
• ブラウザーの自動起動に対応したシンプルな OAuth2 認証フロー
• デスクトップアプリとウェブアプリの両方の認証情報に対応
• 利便性を高めるグローバルな認証情報の保存

インストールと認証

npm からインストール（推奨）

npx @artymclabin/gmail-mcp auth

ソースからインストール

git clone https://github.com/ArtyMcLabin/Gmail-MCP-Server.git
cd Gmail-MCP-Server
npm install
npm run build

注: 古いドキュメントに記載されている npx @gongrzhe/server-gmail-autoauth-mcp コマンドは、メンテナンスされていない上流のフォークを参照しています。このフォークは @artymclabin/gmail-mcp として公開されています。

Google Cloud 認証情報の設定

1. Google Cloud プロジェクトを作成し、認証情報を取得します。

   a. Google Cloud プロジェクトを作成します。

   • Google Cloud Console にアクセスします
   • 新しいプロジェクトを作成するか、既存のプロジェクトを選択します
   • プロジェクトで Gmail API を有効にします

   b. OAuth 2.0 認証情報を作成します。

   • 「API とサービス」>「認証情報」に移動します
   • 「認証情報を作成」>「OAuth クライアント ID」をクリックします
   • アプリケーションの種類として「デスクトップアプリ」または「ウェブ アプリケーション」を選択します
   • 名前を付けて「作成」をクリックします
   • ウェブ アプリケーションの場合は、認証済みのリダイレクト URI に http://localhost:3000/oauth2callback を追加します
   • クライアントの OAuth キーが含まれる JSON ファイルをダウンロードします
   • キーファイルの名前を gcp-oauth.keys.json に変更します

2. 認証を実行します。

   次の 2 つの方法で認証できます。

   a. グローバル認証（推奨）：

   # First time: Place gcp-oauth.keys.json in your home directory's .gmail-mcp folder
   mkdir -p ~/.gmail-mcp
   mv gcp-oauth.keys.json ~/.gmail-mcp/
   
   # Run authentication from anywhere
   node dist/index.js auth
   

   b. ローカル認証：

   # Place gcp-oauth.keys.json in your current directory
   # The file will be automatically copied to global config
   node dist/index.js auth
   

   認証プロセスでは、次の処理が行われます。

   • 現在のディレクトリまたは ~/.gmail-mcp/ にある gcp-oauth.keys.json を検索します
   • 現在のディレクトリに見つかった場合、~/.gmail-mcp/ にコピーします
   • Google 認証のためにデフォルトのブラウザーを開きます
   • 認証情報を ~/.gmail-mcp/credentials.json に保存します

   注：

   • 認証が成功すると、認証情報は ~/.gmail-mcp/ にグローバルに保存され、どのディレクトリからでも使用できます
   • デスクトップアプリとウェブ アプリケーションの両方の認証情報に対応しています
   • ウェブ アプリケーションの認証情報の場合、認証済みのリダイレクト URI に http://localhost:3000/oauth2callback を追加してください

   カスタムコールバック URL／ポート： デフォルトでは、ローカル OAuth サーバーはポート 3000 の /oauth2callback で待ち受けます。ポート 3000 が使用できない場合や、別のリダイレクト URI が必要な場合は、引数として完全なコールバック URL を渡してください。リスナーは、その URL のポートとパスに自動的にバインドします。

   node dist/index.js auth http://localhost:8080/oauth2callback
   

   渡す URL は、Google Cloud Console に登録されている認証済みリダイレクト URI のいずれかと完全に一致する必要があります。

3. Claude Desktop で設定します。

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

Docker のサポート

Docker の使用を希望する場合：

1. 認証：

docker run -i --rm \
  --mount type=bind,source=/path/to/gcp-oauth.keys.json,target=/gcp-oauth.keys.json \
  -v mcp-gmail:/gmail-server \
  -e GMAIL_OAUTH_PATH=/gcp-oauth.keys.json \
  -e "GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json" \
  -p 3000:3000 \
  mcp/gmail auth

2. 使用方法：

{
  "mcpServers": {
    "gmail": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "mcp-gmail:/gmail-server",
        "-e",
        "GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json",
        "mcp/gmail"
      ]
    }
  }
}

クラウドサーバーでの認証

n8n などのクラウドサーバー環境では、認証時にカスタムコールバック URL を指定できます。

node dist/index.js auth https://gmail.gongrzhe.com/oauth2callback

クラウド環境でのセットアップ手順

1. リバースプロキシを設定する：

   • 認証用のポートを公開するように n8n コンテナを設定します
   • ドメイン（例：gmail.gongrzhe.com）からこのポートにトラフィックを転送するようにリバースプロキシを設定します

2. DNS を設定する：

   • DNS 設定に A レコードを追加し、ドメインがクラウドサーバーの IP アドレスに解決されるようにします

3. Google Cloud Platform を設定する：

   • Google Cloud Console で、カスタムドメインのコールバック URL（例：https://gmail.gongrzhe.com/oauth2callback）を認証済みリダイレクト URI のリストに追加します

4. 認証を実行する：

   node dist/index.js auth https://gmail.gongrzhe.com/oauth2callback
   

5. アプリケーションで設定する：

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

この方法により、コンテナ化されたアプリケーションやクラウドサーバーなど、localhost にアクセスできない環境でも認証フローを適切に動作させることができます。

OAuth スコープ

認証時に OAuth スコープを指定することで、サーバーの Gmail へのアクセスを制限できます。これにより、LLM で利用できるツールを制御し、機密性の高い操作に対する攻撃対象領域を縮小できます。

利用可能なスコープ

スコープ	説明
gmail.readonly	メールへの読み取り専用アクセス（検索、読み取り、添付ファイルのダウンロード）
gmail.modify	メールへの完全な読み取り／書き込みアクセス（readonly の上位互換で、送信、変更、削除を含みます）
gmail.compose	下書きの作成とメールの送信のみ
gmail.send	メールの送信のみ
gmail.labels	ラベルの管理のみ
gmail.settings.basic	フィルターと設定の管理

注：gmail.modify はすべての読み取り機能を含む上位互換のスコープです。gmail.modify を使用する場合、gmail.readonly は必要ありません。

特定のスコープで認証する

必要な権限のみをリクエストするには、--scopes フラグを使用します。

# Read-only access (recommended for safe browsing)
node dist/index.js auth --scopes=gmail.readonly

# Read-only with filter management
node dist/index.js auth --scopes=gmail.readonly,gmail.settings.basic

# Full access (default behavior)
node dist/index.js auth --scopes=gmail.modify,gmail.settings.basic

--scopes フラグを指定しない場合、サーバーはすべての機能を利用できるよう、デフォルトで gmail.modify,gmail.settings.basic を使用します。

スコープとツールの対応

サーバーは、認可されたスコープに基づいて利用可能なツールを自動的に絞り込みます。

ツール	必要なスコープ（いずれか）
read_email、search_emails、download_attachment	gmail.readonly または gmail.modify
list_email_labels	gmail.readonly、gmail.modify、または gmail.labels
send_email、draft_email、reply_all、send_draft	gmail.modify、gmail.compose、または gmail.send
delete_draft、update_draft	gmail.modify または gmail.compose
modify_email、batch_modify_emails、modify_thread、report_phishing、batch_report_phishing	gmail.modify
delete_email、batch_delete_emails	gmail.full（https://mail.google.com/）
create_label、update_label、delete_label、get_or_create_label	gmail.modify または gmail.labels
list_filters、get_filter、create_filter、delete_filter、create_filter_from_template	gmail.settings.basic

gmail.full は完全削除の機能を付与するため、デフォルトのスコープとは意図的に分けられています。アーカイブ、既読への変更、ラベル付け、受信トレイの整理には、modify_email／batch_modify_emails を優先してください。アシスタントがメールを完全に削除できる必要がある場合に限り、--scopes=gmail.full,gmail.settings.basic で再認証してください。gmail.full は他のメール用スコープを包含するため、この組み合わせでは、読み取り、送信、変更、ラベル付けに関するすべてのツールを利用できます（設定用スコープは別扱いです。Gmail のフィルター用エンドポイントが受け付けるのは gmail.settings.* のみです）。

再認証

スコープを変更するには、異なるスコープを指定して認証コマンドを再度実行します。既存の認証情報は置き換えられます。

Claude Code CLI の設定

この MCP サーバーを Claude Code で使用するには、MCP 設定に追加します。

読み取り専用の設定（安全な閲覧に推奨）

まず、読み取り専用のスコープで認証します。

node dist/index.js auth --scopes=gmail.readonly

次に、Claude Code の MCP 設定（~/.claude/mcp_settings.json またはプロジェクトレベルの .mcp.json）に追加します。

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["/absolute/path/to/Gmail-MCP-Server/dist/index.js"]
    }
  }
}

読み取り専用のスコープでは、Claude で利用できるツールは次の 4 つのみです。

• read_email - メールの内容を読み取ります
• search_emails - 受信トレイを検索します
• list_email_labels - 利用可能なラベルを一覧表示します
• download_attachment - 添付ファイルをダウンロードします

フルアクセスの設定

Gmail の管理機能をすべて利用するには、次のように設定します。

node dist/index.js auth --scopes=gmail.modify,gmail.settings.basic

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["/absolute/path/to/Gmail-MCP-Server/dist/index.js"]
    }
  }
}

これにより、メールの送信、ラベルの管理、フィルターの作成、全員への返信、スレッド操作、フィッシングの報告、一括操作など、23 個すべてのツールが有効になります。

複数のインスタンスを実行する（ツール名のプレフィックス）

一部の MCP クライアントは、サーバー間でベース名が同じツール項目を重複排除するため、このサーバーの 2 つのインスタンス（たとえば、個人アカウント用と共有受信トレイ用）を並行して実行できません。両方のサーバーが接続済みと報告されても、ツールが表示されるのは一方のインスタンスのみです。

サーバーでは、任意の --tool-prefix=<value> CLI フラグ（または GMAIL_MCP_TOOL_PREFIX 環境変数）を指定できます。指定した値は、登録時にすべてのツール名の先頭に付加されます。デフォルトは空で、完全な後方互換性があります。

例：Claude Code で異なるプレフィックスを指定して 2 つのインスタンスを登録します。

# Personal account
claude mcp add gmail-personal -s user \
  -e GMAIL_CREDENTIALS_PATH=$HOME/.gmail-mcp/credentials-personal.json \
  -- node /absolute/path/to/Gmail-MCP-Server/dist/index.js --tool-prefix=personal_

# Shared inbox
claude mcp add gmail-info -s user \
  -- node /absolute/path/to/Gmail-MCP-Server/dist/index.js --tool-prefix=info_

これにより、ツールは mcp__gmail-personal__personal_search_emails、mcp__gmail-info__info_search_emails などとして表示され、あらゆる階層で区別されます。ディスパッチハンドラーはプレフィックスを取り除き、getToolByName で解決後の名前を検索します。既知のツールと一致する場合にのみプレフィックスを取り除くため、プレフィックスの値が実際のツール名と重なっていても、誤ったディスパッチが通知されないまま発生することはありません。

auth サブコマンドはサーバーの起動前に実行されるため、影響を受けません。--tool-prefix を指定せずに実行してください。

利用可能なツール

サーバーは、Claude Desktop から使用できる次のツールを提供します。

1. メールを送信（send_email）

新しいメールをすぐに送信します。プレーンテキスト、HTML、マルチパート形式のメールに対応し、任意でファイル添付やインライン画像を追加できます。

基本的なメール：

{
  "to": ["[email protected]"],
  "subject": "Meeting Tomorrow",
  "body": "Hi,\n\nJust a reminder about our meeting tomorrow at 10 AM.\n\nBest regards",
  "cc": ["[email protected]"],
  "bcc": ["[email protected]"],
  "mimeType": "text/plain"
}

添付ファイル付きメール：

{
  "to": ["[email protected]"],
  "subject": "Project Files",
  "body": "Hi,\n\nPlease find the project files attached.\n\nBest regards",
  "attachments": [
    "/path/to/document.pdf",
    "/path/to/spreadsheet.xlsx",
    "/path/to/presentation.pptx"
  ]
}

HTML メールの例：

{
  "to": ["[email protected]"],
  "subject": "Meeting Tomorrow",
  "mimeType": "text/html",
  "body": "<html><body><h1>Meeting Reminder</h1><p>Just a reminder about our <b>meeting tomorrow</b> at 10 AM.</p><p>Best regards</p></body></html>"
}

マルチパートメールの例（HTML + プレーンテキスト）：

{
  "to": ["[email protected]"],
  "subject": "Meeting Tomorrow",
  "mimeType": "multipart/alternative",
  "body": "Hi,\n\nJust a reminder about our meeting tomorrow at 10 AM.\n\nBest regards",
  "htmlBody": "<html><body><h1>Meeting Reminder</h1><p>Just a reminder about our <b>meeting tomorrow</b> at 10 AM.</p><p>Best regards</p></body></html>"
}

インライン画像（HTML に埋め込み）：

画像を HTML の本文に埋め込むと、個別の添付ファイルとして届くのではなく、本文内に表示できます。各画像は cid を使って htmlBody から参照し、ファイルの path または base64 の content として指定します。draft_email、update_draft、reply_all でも同様に使用できます。

{
  "to": ["[email protected]"],
  "subject": "Quarterly Report",
  "body": "Revenue is up. See the chart below.",
  "htmlBody": "<p>Revenue is up:</p><img src=\"cid:chart1\">",
  "inlineImages": [
    { "cid": "chart1", "path": "/path/to/chart.png" }
  ]
}

2. メールの下書き（draft_email）

送信せずにメールの下書きを作成します。添付ファイルにも対応しています。

{
  "to": ["[email protected]"],
  "subject": "Draft Report",
  "body": "Here's the draft report for your review.",
  "cc": ["[email protected]"],
  "attachments": ["/path/to/draft_report.docx"]
}

3. メールを読む（read_email）

ID を指定して、特定のメールの内容を取得します。添付ファイルの情報も拡充して表示されるようになりました。

{
  "messageId": "182ab45cd67ef"
}

拡充されたレスポンスには、CC/BCC ヘッダー（存在する場合）と添付ファイルの詳細が含まれます：

Subject: Project Files
From: [email protected]
To: [email protected]
CC: [email protected]
Date: Thu, 19 Jun 2025 10:30:00 -0400

Email body content here...

Attachments (2):
- document.pdf (application/pdf, 245 KB, ID: ANGjdJ9fkTs-i3GCQo5o97f_itG...)
- spreadsheet.xlsx (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, 89 KB, ID: BWHkeL8gkUt-j4HDRp6o98g_juI...)

4. 添付ファイルをダウンロード（download_attachment）

新機能：メールの添付ファイルをローカルファイルシステムにダウンロードします。

{
  "messageId": "182ab45cd67ef",
  "attachmentId": "ANGjdJ9fkTs-i3GCQo5o97f_itG...",
  "savePath": "/path/to/downloads",
  "filename": "downloaded_document.pdf"
}

パラメーター：

• messageId：添付ファイルを含むメールの ID
• attachmentId：添付ファイルの ID（拡充されたメール表示に表示されます）
• savePath：ファイルの保存先ディレクトリ（省略可能。既定では現在のディレクトリ）
• filename：カスタムファイル名（省略可能。指定しない場合は元のファイル名を使用します）

5. メールを検索（search_emails）

Gmail の検索構文を使用してメールを検索します。

{
  "query": "from:[email protected] after:2024/01/01 has:attachment",
  "maxResults": 10
}

6. メールを変更（modify_email）

メールのラベルを追加または削除します（別のフォルダーへの移動、アーカイブなど）。

{
  "messageId": "182ab45cd67ef",
  "addLabelIds": ["IMPORTANT"],
  "removeLabelIds": ["INBOX"]
}

7. メールを削除（delete_email）

メールを完全に削除します。このツールには gmail.full（https://mail.google.com/）が必要です。Gmail の完全削除エンドポイントでは、既定の gmail.modify スコープだけでは不十分です。

{
  "messageId": "182ab45cd67ef"
}

8. メールラベルを一覧表示（list_email_labels）

利用可能なすべての Gmail ラベルを取得します。

{}

9. ラベルを作成（create_label）

新しい Gmail ラベルを作成します。

{
  "name": "Important Projects",
  "messageListVisibility": "show",
  "labelListVisibility": "labelShow"
}

10. ラベルを更新（update_label）

既存の Gmail ラベルを更新します。

{
  "id": "Label_1234567890",
  "name": "Urgent Projects",
  "messageListVisibility": "show",
  "labelListVisibility": "labelShow"
}

11. ラベルを削除（delete_label）

Gmail ラベルを削除します。

{
  "id": "Label_1234567890"
}

12. ラベルを取得または作成（get_or_create_label）

名前で既存のラベルを取得し、存在しない場合は作成します。

{
  "name": "Project XYZ",
  "messageListVisibility": "show",
  "labelListVisibility": "labelShow"
}

13. メールを一括変更（batch_modify_emails）

効率的なバッチ処理で複数のメールのラベルを変更します。

{
  "messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
  "addLabelIds": ["IMPORTANT"],
  "removeLabelIds": ["INBOX"],
  "batchSize": 50
}

14. メールを一括削除（batch_delete_emails）

効率的なバッチ処理で複数のメールを完全に削除します。このツールには gmail.full（https://mail.google.com/）が必要です。Gmail の完全削除エンドポイントでは、既定の gmail.modify スコープだけでは不十分です。

{
  "messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
  "batchSize": 50
}

15. フィルターを作成（create_filter）

カスタム条件とアクションを指定して、新しい Gmail フィルターを作成します。

{
  "criteria": {
    "from": "[email protected]",
    "hasAttachment": false
  },
  "action": {
    "addLabelIds": ["Label_Newsletter"],
    "removeLabelIds": ["INBOX"]
  }
}

16. フィルターを一覧表示（list_filters）

すべての Gmail フィルターを取得します。

{}

17. フィルターを取得（get_filter）

特定の Gmail フィルターの詳細を取得します。

{
  "filterId": "ANe1Bmj1234567890"
}

18. フィルターを削除（delete_filter）

Gmail フィルターを削除します。

{
  "filterId": "ANe1Bmj1234567890"
}

19. テンプレートからフィルターを作成（create_filter_from_template）

一般的な用途向けに事前定義されたテンプレートを使用して、フィルターを作成します。

{
  "template": "fromSender",
  "parameters": {
    "senderEmail": "[email protected]",
    "labelIds": ["Label_GitHub"],
    "archive": true
  }
}

20. 全員に返信（reply_all）

メールのすべての宛先に返信します。元のメールを自動的に取得して宛先リストを作成し、適切なスレッドヘッダー（In-Reply-To、References、threadId）を設定します。

仕組み：

1. messageId で元のメールを取得します
2. 元の送信者（From ヘッダー）を To に設定します
3. 元の To と CC から、自分自身のメールアドレスを除外して CC を作成します
4. 返信が正しいスレッドに入るようにスレッドヘッダーを設定します
5. 既存の send_email パイプラインを使用して送信します（添付ファイル、HTML、マルチパートに対応）

{
  "messageId": "182ab45cd67ef",
  "body": "Thanks for the update, everyone. I'll review and get back to you.",
  "mimeType": "text/plain"
}

HTML と添付ファイルを使用する場合：

{
  "messageId": "182ab45cd67ef",
  "body": "Plain text fallback",
  "htmlBody": "<p>Thanks for the update. See attached notes.</p>",
  "mimeType": "multipart/alternative",
  "attachments": ["/path/to/notes.pdf"]
}

パラメーター：

• messageId（必須）：返信するメールの ID
• body（必須）：返信本文（プレーンテキスト、またはマルチパート使用時のフォールバック）
• htmlBody（任意）：返信本文の HTML 版
• mimeType（任意）：text/plain（デフォルト）、text/html、または multipart/alternative
• attachments（任意）：添付するファイルパスの配列

21. スレッドを変更（modify_thread）

スレッド全体（すべてのメッセージ）に付けられたラベルを一括で変更します。最新のメッセージだけをアーカイブすると、古いメッセージが受信トレイに残る問題を解決します。

{
  "threadId": "182ab45cd67ef",
  "addLabelIds": ["IMPORTANT"],
  "removeLabelIds": ["INBOX"]
}

22. フィッシングを報告（report_phishing）

SPAM ラベルを付けることで、公開 Gmail API で可能な最も近い動作を使用して、メッセージをフィッシングとして報告します。

{
  "messageId": "182ab45cd67ef"
}

注：Gmail API では、ネイティブの「フィッシングを報告」ワークフロー全体は公開されていません。このツールは、利用可能な最も近い代替手段として SPAM ラベルを付けます。

23. 複数のフィッシング報告（batch_report_phishing）

複数のメッセージを効率的なバッチ処理でフィッシングとして報告します。

{
  "messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
  "batchSize": 50
}

24. 下書きを送信（send_draft）

users.drafts.send を使って既存の下書きを一括で送信し、同じ操作内で下書きフォルダーから削除します。孤立した下書きやゴースト下書きが残ることはありません。内容を確認した後、draft_email（または update_draft）に続けて使用します。

{
  "draftId": "r-1234567890123456789"
}

25. 下書きを更新（update_draft）

users.drafts.update を使って下書きの内容をその場で置き換え、下書き ID を保持します。反復作業（下書き → ユーザーからの変更依頼 → 下書きの再作成）で、下書きフォルダーに同じ内容のコピーが何通も増えるのを防ぐために重要です。draft_email と同じ MIME ビルダーを再利用するため、添付ファイルとスレッドの扱いも同じです。

{
  "draftId": "r-1234567890123456789",
  "to": ["[email protected]"],
  "subject": "Revised Report",
  "body": "Updated draft content.",
  "cc": ["[email protected]"],
  "attachments": ["/path/to/report.docx"]
}

26. 下書きを削除（delete_draft）

users.drafts.delete を使って、不要になった下書きを破棄します。

{
  "draftId": "r-1234567890123456789"
}

標準的な下書きのライフサイクル

draft_email(...) → draftId
  ↓ (user wants changes)
update_draft(draftId, ...)   // mutate in place, same ID
  ↓ (user confirms)
send_draft(draftId)          // atomic send + draft removal

または中止する場合：delete_draft(draftId)。

フィルター管理機能

フィルター条件

さまざまな条件に基づいてフィルターを作成できます。

条件	例	説明
from	"[email protected]"	特定の送信者からのメール
to	"[email protected]"	特定の宛先に送信されたメール
subject	"Meeting"	件名に特定のテキストを含むメール
query	"has:attachment"	Gmail 検索クエリ構文
negatedQuery	"spam"	含まれていてはならないテキスト
hasAttachment	true	添付ファイルのあるメール
size	10485760	メールのサイズ（バイト単位）
sizeComparison	"larger"	サイズの比較（larger、smaller）

フィルターのアクション

フィルターでは、次のアクションを実行できます。

アクション	例	説明
addLabelIds	["IMPORTANT", "Label_Work"]	一致するメールにラベルを追加します
removeLabelIds	["INBOX", "UNREAD"]	一致するメールからラベルを削除します
forward	"[email protected]"	メールを別のアドレスに転送します

フィルターテンプレート

サーバーには、よく使われるフィルター条件の事前作成済みテンプレートが含まれています。

1. 送信者テンプレート（fromSender）

特定の送信者からのメールをフィルターし、必要に応じてアーカイブします。

{
  "template": "fromSender",
  "parameters": {
    "senderEmail": "[email protected]",
    "labelIds": ["Label_Newsletter"],
    "archive": true
  }
}

2. 件名フィルターテンプレート（withSubject）

件名に特定のテキストを含むメールをフィルターし、必要に応じて既読にします。

{
  "template": "withSubject",
  "parameters": {
    "subjectText": "[URGENT]",
    "labelIds": ["Label_Urgent"],
    "markAsRead": false
  }
}

3. 添付ファイルフィルターテンプレート（withAttachments）

添付ファイルのあるすべてのメールをフィルターします。

{
  "template": "withAttachments",
  "parameters": {
    "labelIds": ["Label_Attachments"]
  }
}

4. 大容量メールテンプレート（largeEmails）

指定したサイズを超えるメールをフィルタリングします。

{
  "template": "largeEmails",
  "parameters": {
    "sizeInBytes": 10485760,
    "labelIds": ["Label_Large"]
  }
}

5. コンテンツフィルターテンプレート（containingText）

特定のテキストを含むメールをフィルタリングし、必要に応じて重要マークを付けます。

{
  "template": "containingText",
  "parameters": {
    "searchText": "invoice",
    "labelIds": ["Label_Finance"],
    "markImportant": true
  }
}

6. メーリングリストテンプレート（mailingList）

メーリングリストのメールをフィルタリングし、必要に応じてアーカイブします。

{
  "template": "mailingList",
  "parameters": {
    "listIdentifier": "dev-team",
    "labelIds": ["Label_DevTeam"],
    "archive": true
  }
}

フィルターの一般的な例

実用的なフィルターの例を紹介します。

ニュースレターを自動で整理する：

{
  "criteria": {
    "from": "[email protected]"
  },
  "action": {
    "addLabelIds": ["Label_Newsletter"],
    "removeLabelIds": ["INBOX"]
  }
}

プロモーションメールを処理する：

{
  "criteria": {
    "query": "unsubscribe OR promotional"
  },
  "action": {
    "addLabelIds": ["Label_Promotions"],
    "removeLabelIds": ["INBOX", "UNREAD"]
  }
}

上司からの優先メール：

{
  "criteria": {
    "from": "[email protected]"
  },
  "action": {
    "addLabelIds": ["IMPORTANT", "Label_Boss"]
  }
}

大きな添付ファイル：

{
  "criteria": {
    "size": 10485760,
    "sizeComparison": "larger",
    "hasAttachment": true
  },
  "action": {
    "addLabelIds": ["Label_LargeFiles"]
  }
}

高度な検索構文

search_emails ツールは、Gmail の強力な検索演算子に対応しています。

演算子	例	説明
from:	from:[email protected]	特定の送信者からのメール
to:	to:[email protected]	特定の宛先に送信されたメール
subject:	subject:"meeting notes"	件名に特定のテキストを含むメール
has:attachment	has:attachment	添付ファイルのあるメール
after:	after:2024/01/01	指定した日付より後に受信したメール
before:	before:2024/02/01	指定した日付より前に受信したメール
is:	is:unread	特定の状態のメール
label:	label:work	特定のラベルが付いたメール

複数の演算子を組み合わせることもできます：from:[email protected] after:2024/01/01 has:attachment

高度な機能

メール添付ファイルのサポート

このサーバーは、添付ファイルに関する包括的な機能を提供します。

• 添付ファイルの送信：メールの送信時または下書き作成時に、attachments 配列にファイルパスを指定します
• 添付ファイルの検出：MIME タイプとファイルサイズを自動的に検出します
• ダウンロード機能：メールの添付ファイルをローカルファイルシステムにダウンロードできます
• 表示の強化：ファイル名、種類、サイズ、ダウンロード ID など、添付ファイルの詳細情報を確認できます
• 複数形式への対応：一般的なすべてのファイル形式（ドキュメント、画像、アーカイブなど）に対応しています
• RFC822 準拠：Nodemailer を使用して、適切な MIME メッセージ形式を作成します

対応ファイル形式：PDF、DOCX、XLSX、PPTX、画像（PNG、JPG、GIF）、アーカイブ（ZIP、RAR）など、標準的なすべてのファイル形式に対応しています。

メール内容の抽出

このサーバーは、複雑な MIME 構造からメールの内容を適切に抽出します。

• プレーンテキストがある場合は、優先して使用します
• プレーンテキストがない場合は、HTML コンテンツを使用します
• ネストされたパートを含むマルチパート MIME メッセージを処理します
• 添付ファイルの情報（ファイル名、種類、サイズ、ダウンロード ID）を処理します
• 元のメールヘッダー（From、To、Subject、Date）を保持します

国際文字のサポート

このサーバーは、メールの件名と内容に含まれる、ASCII 以外の文字を完全にサポートしています。以下が含まれます。

• トルコ語、中国語、日本語、韓国語、その他の非ラテン文字のアルファベット
• 特殊文字や記号
• 適切なエンコードにより、メールクライアントで正しく表示されます

包括的なラベル管理

このサーバーは、Gmail のラベルを管理するためのツール一式を提供します。

• ラベルの作成：表示設定をカスタマイズして新しいラベルを作成します
• ラベルの更新：ラベル名を変更したり、表示設定を変更したりします
• ラベルの削除：ユーザーが作成したラベルを削除します（システムラベルは保護されています）
• 検索または作成：名前でラベルを取得するか、見つからない場合は自動的に作成します
• すべてのラベルを一覧表示：すべてのシステムラベルとユーザーラベルの詳細情報を確認できます
• ラベルの表示オプション：メッセージとラベルの一覧でのラベルの表示方法を制御します

ラベルの表示設定は次のとおりです。

• messageListVisibility：メッセージ一覧でラベルを表示するかどうかを制御します（show または hide）
• labelListVisibility：ラベル一覧でのラベルの表示方法を制御します（labelShow、labelShowIfUnread、または labelHide）

これらのラベル管理機能を使用すると、Gmail のインターフェースに切り替えることなく、Claude を通じてメールを高度に整理できます。

バッチ操作

サーバーには、効率的なバッチ処理機能が含まれています。

• 一度に最大50件のメールを処理できます（バッチサイズは設定可能です）
• 大量のメールセットを自動的に分割し、API の制限を回避します
• 各操作の成功・失敗を詳細に報告します
• 個別に再試行することで、エラーを適切に処理します
• 受信トレイの一括管理や整理タスクに最適です

セキュリティに関する注意事項

• OAuth 認証情報はローカル環境（~/.gmail-mcp/）に安全に保存されます
• サーバーは永続的な認証を維持するため、オフラインアクセスを使用します
• 認証情報を共有したり、バージョン管理にコミットしたりしないでください
• Google アカウントの設定で、使用していないアクセス権を定期的に確認し、取り消してください
• 認証情報はグローバルに保存されますが、アクセスできるのは現在のユーザーのみです
• 添付ファイルはローカルで処理され、サーバーに永続的に保存されることはありません

トラブルシューティング

1. OAuth キーが見つからない

   • gcp-oauth.keys.json が現在のディレクトリまたは ~/.gmail-mcp/ にあることを確認してください
   • ファイルのアクセス権を確認してください

2. 認証情報の形式が無効

   • OAuth キーファイルに web または installed の認証情報が含まれていることを確認してください
   • ウェブアプリケーションの場合は、リダイレクト URI が正しく設定されていることを確認してください

3. ポートがすでに使用されている

   • デフォルトでは認証にポート3000が使用されます。認証を実行する前にポートを空けるか、カスタムのコールバック URL を渡して別のポートで実行してください（例：node dist/index.js auth http://localhost:8080/oauth2callback）
   • ポート3000を空けるには、そのポートを使用しているプロセスを見つけて停止します
   • カスタムのコールバック URL は、Google Cloud Console に登録されている承認済みリダイレクト URI のいずれかと一致する必要があります

4. バッチ操作の失敗

   • バッチ操作が失敗した場合、個々の項目は自動的に再試行されます
   • 詳細なエラーメッセージを確認し、具体的な失敗内容を確認してください
   • レート制限が発生する場合は、バッチサイズを小さくすることを検討してください

5. 添付ファイルに関する問題

   • ファイルが見つからない：添付ファイルのパスが正しく、アクセス可能であることを確認してください
   • アクセス権エラー：サーバーに添付ファイルの読み取り権限があることを確認してください
   • サイズ制限：Gmail では、メール1件あたりの添付ファイルのサイズ上限は25MBです
   • ダウンロードの失敗：ダウンロードディレクトリへの書き込み権限があることを確認してください

コントリビューション

コントリビューションを歓迎します！お気軽に Pull Request を送信してください。

ブランチのワークフロー

このリポジトリでは、2ブランチモデルを採用しています。

• main - 安定版です。動作が確認された後、experimental から昇格した変更のみを受け入れます。PR が main に直接マージされることはありません。
• experimental - ステージング／アクティブな開発用です。すべての PR はここを対象に変更され、まず experimental にマージされます。

コントリビューションのライフサイクル：

PR opened (any base)
  → retargeted to `experimental`
  → security audit + review + CI
  → merged into `experimental`
  → soak / verify on experimental
  → `experimental` promoted to `main` (maintainer confirms)

可能であれば、experimental を対象に PR を作成してください。main を対象にした場合、メンテナーがマージ前に experimental を対象とするよう変更します。

CI では README の更新が必須です - main へのすべてのプッシュとすべての PR に、README.md の変更を含める必要があります（バージョン更新や変更履歴の追加でもかまいません）。これにより、コードベースの進化に合わせてドキュメントを最新の状態に保てます。

依存関係の更新や CI 設定の変更など、実際にドキュメントの更新が不要なコミットでこの要件を回避するには、コミットメッセージまたは PR のタイトルに [skip-readme] または [no-readme] を含めてください。

評価の実行

evals パッケージは MCP クライアントを読み込み、そのクライアントが index.ts ファイルを実行するため、テストのたびに再ビルドする必要はありません。npx コマンドの前に環境変数を指定して読み込むことができます。詳細なドキュメントはこちらをご覧ください。

OPENAI_API_KEY=your-key  npx mcp-eval src/evals/evals.ts src/index.ts

ライセンス

MIT

サポート

問題が発生した場合や質問がある場合は、issue を作成してください。