google-workspace-mcp

Gmail + Calendar + Drive + Docs + Sheetsに対応した、マルチアカウントかつトークン効率の高いMCPです。公式のClaudeコネクタが1つのアカウントしかサポートしておらず、デフォルトでメッセージやファイルの本文全体を返してしまうという課題を解決するために構築されました。

なぜこれが必要なのか

マルチアカウント: 複数のメールボックス（仕事用、個人用、共同創業者用など）をOAuthで管理できます。すべてのツールで account メールアドレスを指定し、Send-As（送信者名）IDを介してエイリアスを処理します。
トークン効率: 検索やリスト取得ではコンパクトな形式（メールなら {id, from, subject, snippet, ...}、Driveなら {id, name, mime, modified, size, ...}）で返されます。本文やファイルの内容は必要な場合のみ取得します。
キーチェーンベース: リフレッシュトークンはプレーンテキストファイルではなく、macOSキーチェーンに保存されます。Vaultやリポジトリにトークンが含まれることはありません。

ツール (v2, 61ツール)

アカウント管理 (3)

gws_account_add — ブラウザでのOAuthフローを実行し、新しい認証済みメールボックスを追加します
gws_account_list — 認証済みアカウントとデフォルトアカウントを一覧表示します
gws_account_remove — ローカルの認証情報を削除します（Google側の権限は取り消されません）

Gmail (10)

gmail_search — Gmail演算子を使用して検索します。コンパクトなレスポンスを返します。
gmail_read — メッセージ1件またはスレッド全体を読み取ります。本文はオプトインです。
gmail_send — メールを送信します。Send-As ID用の from_alias を指定可能です。
gmail_draft — 下書きを作成します。
gmail_reply — 返信します（スレッドとヘッダーを保持）。reply_all オプションあり。
gmail_labels_list — すべてのラベルを一覧表示します。
gmail_label_apply — ラベルの一括追加/削除を行います。
gmail_archive — 一括アーカイブ（受信トレイから削除）を行います。
gmail_trash — 一括でゴミ箱へ移動します。
gmail_sendas_list — このメールボックスのSend-As IDを一覧表示します。

Calendar (7)

cal_list_calendars — すべてのカレンダーを一覧表示します。
cal_list_events — 今後の予定を一覧表示します（デフォルトはコンパクト、verbose=True で詳細表示）。
cal_create_event — イベントを作成します。Google Meetリンクの追加も可能です。
cal_update_event — フィールドの部分更新を行います。
cal_delete_event — 削除します。
cal_freebusy — スケジュール調整のために空き時間をチェックします。
cal_respond — 承諾/辞退/仮承諾を行います。

Drive (18)

drive_search — フリーテキストまたはDriveのクエリ構文で検索します。メタデータのみのレスポンスです。
drive_read_file — デフォルトはメタデータのみ。include_content=True で本文を取得します。
drive_list_folder — フォルダの直下にあるファイルを表示します（マイドライブは 'root'）。
drive_create_folder — フォルダを作成します（親フォルダ指定可能）。
drive_upload — ローカルファイルをアップロードします。convert_to_google オプションあり。
drive_move — 親フォルダを変更します。
drive_rename — ファイルまたはフォルダの名前を変更します。
drive_share — メールアドレスを指定して閲覧者/コメント投稿者/編集者などの権限を付与します。
drive_trash — ゴミ箱へ移動します（復元可能）。
drive_untrash — ゴミ箱から復元します。
drive_permission_list — ファイルにアクセス権を持つユーザーを一覧表示します。
drive_permission_update — 権限保持者の役割を変更します。
drive_permission_delete — 権限を取り消します。
drive_shared_drives_list — このアカウントがアクセス可能な共有ドライブを一覧表示します。
drive_comments_list — Driveファイル（ドキュメント/スプレッドシート/スライド/アップロードファイル）のコメントを一覧表示します。
drive_comment_add — コメントを追加します（アンカー指定可能）。
drive_comment_reply — コメントに返信します。
drive_comment_resolve — コメントを解決済みにします。

Docs (9)

docs_create — 新規ドキュメントを作成します（初期本文と親フォルダを指定可能）。
docs_read — デフォルトはプレーンテキスト。structured=True でDocs APIのツリー構造を取得します。
docs_append — 本文の末尾にテキストを追加します。
docs_insert_at — 指定したインデックスにテキストを挿入します。
docs_replace_text — 検索と置換を行い、置換数を返します。
docs_export — markdown / pdf / docx / rtf / plain 形式でエクスポートします。
docs_suggestions_list — 保留中の変更提案を一覧表示します。
docs_suggestions_accept_all — すべての提案を承諾します（ドキュメントを書き換えます）。
docs_suggestions_reject_all — すべての提案を拒否します（ドキュメントを書き換えます）。

Sheets (14)

sheets_create — 新規ワークブックを作成します（親フォルダ指定可能）。
sheets_list_sheets — 行/列のサイズとともにタブを一覧表示します。
sheets_add_sheet — 既存のワークブックに新しいタブを追加します。
sheets_read_range — A1形式の範囲を読み取ります。FORMULA / UNFORMATTED_VALUE オプションあり。
sheets_write_range — 範囲を上書きします。USER_ENTERED で数式を解析します。
sheets_append — 既存データの末尾に行を追加します。
sheets_clear_range — 値をクリアします（書式は保持されます）。
sheets_batch_read — 1回のAPI呼び出しで複数範囲を読み取ります。
sheets_batch_write — 1回のAPI呼び出しで複数範囲に書き込みます。
sheets_named_ranges_list — ワークブック内の名前付き範囲を一覧表示します。
sheets_named_range_add — 名前付き範囲を作成します。
sheets_named_range_delete — 名前付き範囲を削除します。
sheets_conditional_format_add — 条件付き書式ルールを追加します。
sheets_data_validation_add — ドロップダウン / 数値 / メール / URLの検証を設定します。

インストール

GCPの初回セットアップについては SETUP.md を参照してください（v1は約45分、v2でDrive/Docs/Sheetsを有効にする場合は追加で約5分）。

セットアップ後:

pip3 install --break-system-packages -r requirements.txt

Claude Codeへの登録

プロジェクトの .mcp.json（またはグローバルアクセスの場合は ~/.claude.json）に追加してください:

"google-workspace": {
  "type": "stdio",
  "command": "python3",
  "args": ["/path/to/google-workspace-mcp/server.py"]
}

v1からv2へのアップグレード

v2ではDrive + Docs + Sheetsのスコープが追加されました。認証済みのアカウントはそれぞれ一度再OAuthを行う必要があります。これにより、Googleが新しいスコープを許可します。SETUP.mdのステップ6bを参照してください。

ロードマップ

v3: Gmailフィルタ、不在通知、プッシュ通知（Gmail Watch）、カレンダーACL/委任、スライド、フォーム、タスク
v4: サービス間の一括リクエスト、Driveの改訂履歴

ライセンス

MIT

Google Workspace MCP