gmail-attachments-mcp

gmail-attachments-mcp

Gmail の添付ファイルをディスクにダウンロードするための、用途を絞ったModel Context Protocolサーバー（およびスタンドアロン CLI）です。ツールは3つ、OAuth スコープは読み取り専用で、余分な機能はありません。

Claude Desktop のホスト型 claude.ai Gmail コネクターは、添付ファイルのID とメタデータのみを返し、実際のデータは取得できません。このサーバーはその不足を補い、あらゆる MCP クライアント（Claude Code、Claude Desktop、Cursor、Cline など）で使えるほか、cron ジョブやシェルスクリプト用の通常の CLI としても動作します。

添付ファイルのダウンロード機能を使うために @GongRzhe/Gmail-MCP-Server（1.1k★、2026-03-03 にアーカイブ）を利用していた場合、このプロジェクトはその単一機能に特化した最小限の後継です。

機能

• MCP ツールは3つ — gmail_search、gmail_download_thread_attachments、gmail_download_latest_matching。API はこれだけです。
• OAuth スコープは読み取り専用（gmail.readonly）— メールの送信、削除、変更はできません。
• MCP サーバーとスタンドアロン CLI の両方として動作 — 同じコード、同じ認証トークンで、どちらの方法でも利用できます。
• 環境変数で設定 — GMAIL_MCP_CREDENTIALS、GMAIL_MCP_TOKEN、GMAIL_MCP_DEFAULT_DEST_DIR。
• cron での利用に適しています — 一度認証すれば、キャッシュされたリフレッシュトークンにより、ヘッドレスジョブを継続して実行できます。

インストール

pip install gmail-attachments-mcp
# or, with uv:
uv tool install gmail-attachments-mcp

初回セットアップ（約10分）

Google Cloud の OAuth クライアントが必要です。サーバーはすべてご利用のマシン上で動作し、データが外部に送信されることはありません。

1. 添付ファイルをダウンロードする Gmail アカウントでGoogle Cloud Consoleにログインします。
2. プロジェクトを作成するか、既存のプロジェクトを選択します。
3. Gmail API を有効にします：console.cloud.google.com/apis/library/gmail.googleapis.com。
4. API とサービス → OAuth 同意画面で OAuth 同意画面を設定します。
   • Google Workspaceユーザー：ユーザータイプを内部に設定します（アプリの検証は不要です）。
   • 個人の Gmailユーザー：ユーザータイプを外部に設定します。「テストユーザー」にご自身の Gmail アドレスを追加します。
5. API とサービス → 認証情報 → ＋ 認証情報を作成 → OAuth クライアント ID
   • アプリケーションの種類：デスクトップアプリ
   • JSON をダウンロードします。
6. セットアップを実行します。

gmail-attachments-mcp setup --import-credentials ~/Downloads/client_secret_*.json

OAuth の同意を求めるブラウザーウィンドウが開きます。同意すると、リフレッシュトークンが ~/.config/gmail-attachments-mcp/token.json（または $XDG_CONFIG_HOME/gmail-attachments-mcp/）にキャッシュされます。

確認します。

gmail-attachments-mcp status
gmail-attachments-mcp search "has:attachment newer_than:7d" --max 3

スクリーンショットとトラブルシューティングについては、docs/setup-google-oauth.mdを参照してください。

Claude Code から使う

claude mcp add --scope user gmail-attachments gmail-attachments-mcp -- serve

その後、任意の Claude Code セッションで次のように指示します。

gmail-attachments MCP を使って、[email protected] から最新の CV を ~/CVs にダウンロードしてください。

Claude Desktop から使う

~/Library/Application Support/Claude/claude_desktop_config.json（Mac）または %APPDATA%/Claude/claude_desktop_config.json（Windows）を編集します。

{
  "mcpServers": {
    "gmail-attachments": {
      "command": "gmail-attachments-mcp",
      "args": ["serve"]
    }
  }
}

Claude Desktop を再起動します。詳細については、docs/claude-desktop.mdを参照してください。

Cursor / Cline / Continue などから使う

stdio サーバーに対応した MCP クライアントであれば利用できます。同じ gmail-attachments-mcp serve コマンドを指定してください。docs/other-clients.mdを参照してください。

シェルまたは cron から使う

# Search
gmail-attachments-mcp search "from:[email protected] has:attachment newer_than:30d"

# Download every attachment from a specific thread
gmail-attachments-mcp thread 19db831fab15b507 --dest ~/Invoices

# Download from the latest match, only PDFs
gmail-attachments-mcp latest "from:[email protected] has:attachment" --dest ~/CVs --ext .pdf,.docx

cron の例 — CV の添付ファイルを1時間ごとに取得します。

0 * * * * /usr/local/bin/gmail-attachments-mcp latest "to:[email protected] has:attachment newer_than:2d" --dest ~/CVs --ext .pdf,.docx >> ~/.cache/gmail-attachments-mcp.log 2>&1

3つの MCP ツール

gmail_search(query, max_results=10)

添付ファイル名を含むスレッドの概要を返します。Gmail の標準的なクエリ構文を使います。

[
  {
    "thread_id": "19db831fab15b507",
    "subject": "Folon Q3 2026 Quarterly Product Recap",
    "sender": "Manon Muhtasin Rahman <[email protected]>",
    "date": "Thu, 23 Apr 2026 08:35:00 +0600",
    "snippet": "Hi everyone, Attached is...",
    "message_count": 1,
    "attachment_count": 1,
    "attachment_filenames": ["Folon Quarterly Report Q3 2026.pdf"]
  }
]

gmail_download_thread_attachments(thread_id, dest_dir?, extensions?)

スレッド内のすべての添付ファイルをディスクにダウンロードします。ファイルごとに path、size_bytes、mime_type、original_filename を返します。

gmail_download_latest_matching(query, dest_dir?, extensions?)

便利な機能です。検索し、最も新しい一致結果から1回の呼び出しでダウンロードします。

設定

すべてのパスは環境変数で上書きできます。

変数	デフォルト	内容
GMAIL_MCP_CREDENTIALS	~/.config/gmail-attachments-mcp/credentials.json	OAuth クライアントシークレット JSON
GMAIL_MCP_TOKEN	~/.config/gmail-attachments-mcp/token.json	キャッシュされたリフレッシュトークン
GMAIL_MCP_DEFAULT_DEST_DIR	~/Downloads	デフォルトのダウンロード先
GMAIL_MCP_SCOPES	https://www.googleapis.com/auth/gmail.readonly	OAuth スコープ（カンマ区切り）
XDG_CONFIG_HOME	~/.config	標準の XDG 上書き設定

セキュリティ

• トークンの保存：リフレッシュトークンは、モード 0600 で ~/.config/gmail-attachments-mcp/token.json に書き込まれます。アカウントへのシェルアクセス権がある人は誰でも、あなたの Gmail を読めます。このファイルはパスワードと同様に扱ってください。
• OAuth スコープ：デフォルトは gmail.readonly です。メールの送信、削除、変更はできません。$GMAIL_MCP_SCOPES を変更した場合、その結果はご自身の責任となります。
• 認証情報ファイル：OAuth クライアントシークレット JSON はパスワードではなく、Google にアプリを識別させるためのものです。ただし、絶対にコミットしないでください。同梱の .gitignore は一般的なファイル名を除外します。
• OAuth クライアント：クライアントはご自身の Google Cloud プロジェクトにあります。中央サーバーもテレメトリーもなく、データが端末の外部に送信されることはありません。

トラブルシューティング

Claude Desktop／cron から実行したときに No valid Gmail token と表示される 最初の OAuth フローではブラウザーが必要です。ブラウザーを開けるターミナルで gmail-attachments-mcp setup を一度実行してください。以降の実行では、キャッシュされたリフレッシュトークンが使用されます。

Token has been expired or revoked と表示される リフレッシュトークンは、少なくとも 6 か月ごとに使用し、myaccount.google.com/permissions で取り消さなければ有効なままです。再認証するには：

gmail-attachments-mcp setup --reauth

Access blocked: This app's request is invalid と表示される 個人用 Gmail では、OAuth 同意画面の Test users にご自身のアドレスを登録する必要があります。Workspace ユーザーは、これを避けるためにオーディエンスとして Internal を選択してください。

HttpError 403: Request had insufficient authentication scopes と表示される 再認証せずに $GMAIL_MCP_SCOPES を変更しています。gmail-attachments-mcp setup --reauth を実行してください。

他の Gmail MCP サーバーとの比較

サーバー	スコープ	ツール	メンテナンス状況
Anthropic 提供の claude.ai Gmail	読み書き、ホスト型	多数	アクティブですが、添付ファイルのバイトデータは取得できません
GongRzhe/Gmail-MCP-Server	メールボックス全体	19	2026-03-03 にアーカイブ済み
shinzo-labs/gmail-mcp	メールボックス全体	約 30	アクティブ
gmail-attachments-mcp（本ツール）	読み取り専用	3	アクティブ

小規模で目的を絞った読み取り専用ツールをお探しなら、こちらを選んでください。メールの送信やラベル、下書き、スレッドなどの管理も必要なら、より多機能なものを選んでください。

認証 — Google OAuth クライアントをご用意ください

API キーや同梱されたシークレットはありません。サーバーは、ご自身で作成した OAuth クライアントを使ってご自身の Google アカウントに認証し、リフレッシュトークンをローカルにキャッシュします。作者がデータにアクセスすることは一切ありません。

• 独自のクライアントを使う理由：Google の制限付きスコープ（ここでは gmail.readonly）は共有アプリとして再配布できず、未確認の共有アプリはユーザー数が 100 人に制限されます。「独自の OAuth クライアントを用意する」方式は、個人データを扱う MCP サーバーで標準的なパターンです。
• 必要なもの：無料の Google Cloud プロジェクト、有効化した Gmail API、OAuth 同意画面、デスクトップ OAuth クライアントです。詳しい手順はこちら → docs/setup-google-oauth.md。
• トークンの保存場所：~/.config/gmail-attachments-mcp/token.json（モード 0600）。ローカルで無効にするには削除してください。完全に取り消すには myaccount.google.com/permissions をご利用ください。
• ホスト型／SaaS のオプションはありません — すべてローカルで実行され、メールがサードパーティーのサーバーを経由することはありません。

関連ツール

ホスト型コネクターでは公開されていない Google Workspace データを扱う、機能を絞ったローカル MCP サーバー群の一部です。

• gmail-attachments-mcp — Gmail の添付ファイルのバイトデータをディスクにダウンロードします（このリポジトリ）
• google-drive-comments-mcp — Docs／Sheets／Slides のコメントスレッドを読み取ります
• google-drive-files-mcp — Drive のファイルを移動・整理します

OAuth ログインを共有することも、それぞれ独立させることもできます。設定については各リポジトリをご覧ください。

ライセンス

MIT です。LICENSE をご覧ください。

貢献

Issue と PR を歓迎します。提出前に pytest と ruff check src tests を実行してください。

git clone https://github.com/zayansalman/gmail-attachments-mcp
cd gmail-attachments-mcp
pip install -e ".[dev]"
pytest