gmail-mcp

AI エージェント（Claude Code や MCP に対応したその他のツール）向けの、複数アカウント対応 Gmail MCP サーバーです。何よりも優先される設計目標がひとつあります。エージェントは読み取りと下書きの作成を自由に行えますが、送信には必ず人間の承認が必要です。

ホスト型 Gmail コネクタは一度にひとつのアカウントしか扱えず、送信もそのまま通してしまうため、このサーバーを構築しました。このサーバーは、任意の数の Gmail アカウントを短いエイリアス（work、school など）の背後に紐付け、リスクに応じて機能を分割します:

このサーバーは意図的に gmail ではなく gmail-accounts として登録されています。ホスト型 Gmail コネクタも併用している場合、ほぼ同じツール名だとエージェントが間違ったメールボックスを読み、確信を持って false negative を報告してしまうためです。

送信ゲートの仕組み

1. エージェントが下書きを用意し、あなたに承認を求めます。

2. あなたは自分のターミナルで gmail-approve を実行し、正確な RFC822 ペイロードを確認して、その下書きのコンテンツハッシュに紐付けられた一度きりのトークンを取得します。

3. エージェントはトークンを使って送信ツールを呼び出します。間違った下書き、編集された下書き、再利用されたトークン、期限切れのトークンは、すべて拒否されます。

送信ツールは anthropic/requiresUserInteraction も備えているため、Claude Code は bypassPermissions モードでも人間に確認を求めます。トークン CLI は誤操作を防ぐインターロックであり、実際に強制される境界はハーネス側のプロンプトです。

Related MCP server: Gmail Multi-Inbox MCP Server

セットアップ

Python 3.12+ と uv が必要です。

1. Google Cloud OAuth クライアント

console.cloud.google.com でプロジェクトを作成し、Gmail API を有効にして、OAuth クライアント ID（種類: Desktop app） を作成し、JSON を次の場所にダウンロードします:

~/.config/gmail-mcp/client_secret.json

2. アカウントを宣言する

~/.config/gmail-mcp/accounts.json:

{
  "accounts": [
    { "alias": "personal", "email": "alice.personal@gmail.com" },
    { "alias": "work",     "email": "alice.work@gmail.com" }
  ]
}

後からアカウントを追加する場合も、設定の編集と 1 回の認証実行だけで済みます。このファイルは呼び出しのたびに再読込されるため、再起動は不要です。

3. 各アカウントを認証する

uv sync
scripts/auth-all.sh          # runs the OAuth flow once per alias, skips done ones

各認可はエリアスと照合して検証されます。ブラウザで誤った Google アカウントを認証した場合は検出されて拒否され、黙って保存されることはありません。

4. Claude Code に登録する

claude mcp add gmail-accounts -- uv run --directory /path/to/gmail-mcp --frozen --no-sync gmail-mcp

日常的な使い方

すべてのツールは account エリアスを受け取ります。エージェントに「work で請求書のスレッドを検索して」とか「personal で返信の下書きを作成して」のように依頼します。送信するときは:

gmail-approve            # lists pending sends, shows the payload, mints a token

ヘルスチェック:

uv run gmail-mcp-health

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

• 秘密情報がリポジトリに入ることはありません。client_secret.json とアカウントごとのトークンは ~/.config/gmail-mcp/ に置かれます（GMAIL_MCP_CONFIG で上書可能）。

• 設定の書き込みはすべてアトミックです（tmp + fsync + renmae）。書き込み途中でクラッシュしても、不完全なファイルが残ることはありません。

• stdout は JSON-RPC チャネルです。パッケージ内のいかなるコードも print() してはなリません（ruff T201 で強制）。これにより、診断出カがプロトコルを壊すことはありません。

テスト

uv run pytest