gmail-mcp

MCP クライアント向けの Gmail コネクタ。1 つのサーバーで、OAuth リフレッシュトークン経由の複数の Gmail アカウントを扱えます。実際の MIME を送信します（ファイルパス添付、ライブ署名、送信後の証明）。モデルにメガバイト単位の base64 を流し込むことなく、メールの読み取りと整理ができます。

Google がホストする Gmail MCP のラッパーではありません。ホスト上で RFC822 を組み立て、gmail.googleapis.com に直接通信します。

Features

• マルチアカウント OAuth — accounts_add でメールボックスを追加。トークンはローカルに保存（モード 0600）

• 送信 / 返信 / 転送 — サーバーが MIME を構築。送信元は outbox のファイルパスのみ、25 MB 上限、冪等性キー、成功時の証明

• 読み取り / 整理 — 検索（スレッド + ページネーション）、スレッド / メッセージ取得、ラベル、アーカイブ / ゴミ箱、下書き

• 添付ファイル — ~/Outbox（設定可能）から送信し、~/Inbox（設定可能）へダウンロード

• デュアルトランスポート — ローカル実行環境向けの stdio。リモートクライアント向けにゲートウェイ越しの Streamable HTTP

Related MCP server: Gmail MCP Server

Requirements

• Python 3.12+（開発は pyenv 経由で 3.13）

• Google Cloud の Desktop OAuth クライアント（クライアント ID + シークレット）

• 同梱の LaunchAgent スクリプト（HTTP サービス）には macOS。手動実行は Linux でも動作

Quick start

git clone https://github.com/iXanadu/gmcp.git
cd gmcp

# Python 3.12+ (example with pyenv)
pyenv virtualenv 3.13 gmail-mcp-3.13
pyenv local gmail-mcp-3.13
pip install -e '.[dev]'

# Config (see examples/)
cp examples/.env.example .env
cp examples/.keys.example .keys
chmod 600 .keys

# Sanity check
gmail-doctor

HTTP トランスポートを実行する前に、.keys に Google OAuth の認証情報と HTTP ベアラートークンを記入してください。

Google Cloud Console（一度だけ必要）

Desktop OAuth クライアントが必要です。サービスアカウントやドメイン全体の委任ではありません。

最初の accounts_add の際、Google が同意を求めます。スコープはサーバー側で固定されています。メールの読み取り / 送信 / 整理に加え、send-as 署名の読み取り（キャッシュなし）です。

ユーザー名 / パスワード、アプリパスワード、リフレッシュトークンの貼り付けをチャットで行う必要はありません。

メールボックスを接続する（accounts_add）

accounts_add は Google の同意のためにブラウザを開きます。これは stdio トランスポート（gmail-mcp）でのみ動作し、HTTP では実行できません。

gmail-mcp   # stdio — required for accounts_add and accounts_remove

MCP クライアントから accounts_add を呼び出してください。同意が完了すると、サーバーは Google が返した Gmail アドレスを記録します。このアドレスが、他のすべてのツールの account キーになります。

トークンは ~/.config/gmail-mcp/tokens/（モード 0600）に保存されます。必要に応じて、同じサーバーを実行する他のホストにこのディレクトリをコピーしてください。

ヘッドレスサーバー（ローカルにブラウザがない場合）

OAuth コールバックは http://127.0.0.1:8767/oauth/callback です。ディスプレイのないマシンでも、Google のログインページ用にブラウザがどこか必要です。よくある 2 つのパターンは次のとおりです。

A — SSH ポートフォワード（あなたのラップトップで同意）

ヘッドレスホストで stdio MCP / accounts_add を起動します。ラップトップから:

ssh -L 8767:127.0.0.1:8767 user@headless-host

サーバーが出力する認可 URL を開きます（トンネルを確立した状態で、MCP クライアント経由で accounts_add をトリガーしても構いません）。コールバックはトンネル経由でヘッドレスホストの 127.0.0.1:8767 に到達します。

B — デスクトップで同意し、トークンをコピー

ブラウザと同一の .env / .keys を持つ Mac または PC で、accounts_add を一度実行してください。同意後、~/.config/gmail-mcp/tokens/ を本番ホストにコピーします（同じパス、モード 0600）。Google がリフレッシュトークンを失効させない限り、再同意は不要です。

デプロイ構成

一般的な本番環境の分割:

┌─────────────────────┐         ┌──────────────────────────┐
│  Operator machine   │         │  MCP server (Linux/macOS) │
│  (browser for OAuth)│         │  gmail-mcp-http           │
│  accounts_add       │  copy   │  127.0.0.1:8879           │
│  token files ───────┼────────►│  + .env / .keys           │
└─────────────────────┘  tokens └───────────┬──────────────┘
                                            │
                              Cloudflare / gateway / TLS
                                            │
                                    Hand / remote MCP client

• MCP HTTP のために運用者のラップトップをパブリックインターネットに公開しないでください。HTTP はサーバー上のループバック（127.0.0.1:8879）にバインドされます。リバースプロキシが TLS を終端し、そのポートに転送します。

• OAuth はブラウザが存在する場所（運用者のマシンまたは SSH トンネル）で行われます。トークンの JSON ファイルはサーバーにコピーされます。

• ゲートウェイは、OAuth ワークステーションではなく、あなたが管理するサーバーのホスト名（例: mcp.example.com）を指します。

• 長いランダムな GMAIL_MCP_HTTP_BEARER_TOKEN を生成してください。ゲートウェイはこれを Authorization: Bearer … として提示します。

デプロイ後は、gmail-doctor、./scripts/start.sh（macOS LaunchAgent）、または独自の systemd ユニットを実行し、その後 HTTP 経由で accounts_list を呼び出してトークンを確認します。

設定

機密性の低い設定は .env に、シークレットは .keys に置きます（値を入れた状態でどちらもコミットしないでください）。examples/.env.example と examples/.keys.example を参照してください。

設定を変更したら gmail-doctor を実行してください。

トランスポート

stdio（ローカル）

gmail-mcp

accounts_add と accounts_remove を含むすべてのツールを登録します。

Cursor / Claude Code の MCP 設定に、venv の gmail-mcp バイナリと、cwd をリポジトリに設定して組み込みます（これにより .env / .keys が読み込まれます）。

Streamable HTTP（ゲートウェイ）

gmail-mcp-http

デフォルトで 127.0.0.1:8879 にバインドします。Authorization: Bearer <GMAIL_MCP_HTTP_BEARER_TOKEN> が必要です。有効なトークンのないリクエストは 401 になります。

手動許可リスト（HTTP のみ）: 読み取り / 整理ツールに加え、send、reply、forward、draft_create、draft_send、accounts_list、gmail_status。アカウント管理は stdio のままです。

macOS サービス（ユーザー LaunchAgent）

./scripts/start.sh    # install plist → ~/Library/LaunchAgents, load
./scripts/stop.sh
./scripts/restart.sh

チェックアウト先や pyenv の名前が異なる場合は、launchd/com.gmail-mcp.plist のパスを編集してください。ログは logs/ に出力されます。

Linux では、同じループバックバインドで gmail-mcp-http を systemd の下で実行してください。上記のデプロイ構成を参照してください。

ツール

accounts_list、accounts_add、gmail_status を除くすべてのツールは、account 引数（Gmail アドレス）を必要とします。

送信ルール（概要）

• 添付ファイル: { "path": "/absolute/or/under/outbox/file.pdf" } — インライン base64 はなし

• ライブの Gmail 署名が送信時に追加されます（キャッシュなし）

• 署名の後に任意の footer

• 証明を返します: サイズ、href、ok false → ツールエラー（例: 切り詰められた添付ファイル、google.com/url の書き換え）

テスト

pytest tests/ -v

モック化した Gmail HTTP を使用します。実際のメールボックスは不要です。

仕様

製品要件: docs/specs/gmail-mcp-spec.md

ライセンス

Apache-2.0