Google Workspace

@mindstone/mcp-server-google-workspace

Google Workspace MCP サーバー — Gmail、Calendar、Drive、Docs、Sheets、Slides、Contacts、Chat、Meet、Tasks、Forms、Comments、およびアカウント診断。

マルチアカウント対応の Google Workspace MCP です。ホストがオーケストレーションする OAuth（コネクターはコールバックサーバーを実行せず、OAuth URL も生成しません）、アカウントごとの認証情報のアトミックな書き込み、構造化された auth_required ハンドオフにより、サーバーではなくホストがサインインフローを制御します。

ステータス

• バージョン： 0.5.0 · npm：未公開
• 認証： OAuth（ホストによるオーケストレーション）(GOOGLE_CLIENT_SECRET)
• ツール： 124（Gmail、Calendar、Drive、Docs、Sheets、Slides、Contacts、Chat、Meet、Tasks、Forms、Comments、Account）
• サーフェス： cloud-api
• 機械可読： STATUS.json

このコネクターは aaronsb/google-workspace-mcp をベースにしており、package.json#attribution にクレジットを記載しています。

このプロジェクトの目的

2026年初頭にこのプロジェクトを移植した時点では、Google は Workspace 向けの公式 MCP サーバーを公開していませんでした。当時のコミュニティ製の選択肢は、それぞれ役割の一部をうまく果たしていました。ベースとして採用した Aaron Brown の aaronsb/google-workspace-mcp は、Workspace API を幅広くカバーしていましたが、OAuth 時に独自のブラウザーコールバックサーバーを実行していました。これは、ホストアプリケーションがすでに担っている機能です。そこで、MCP ホストが OAuth フロー全体を管理できるようにフォークしました（コネクターはコールバックサーバーを実行したり OAuth URL を計算したりせず、構造化された auth_required 応答を返します）。また、アカウントごとのトークンファイルを制限付き権限でアトミックに書き込み、シンボリックリンクを拒否するようにし、リリースごとにコネクター独自のセキュリティレビューを実施しています。その後、Google の Workspace MCP が公開されましたが、このコネクターはホストの認証情報ファイル構成、ホストがオーケストレーションする OAuth ハンドオフ、復旧ガイダンスの契約との統合を提供するため、引き続き保守しています。現在はこのリポジトリで独立して保守するハードフォークであり、上流プロジェクトの変更は取り込んでいません。

インタラクション例

「Alice が昨日送った、Q3 の計画についてのメールスレッドを見つけて、『ありがとう、今夜読みます』と返信してください。」

ホストが呼び出すツール：

1. search_workspace_emails — Gmail で from:alice@... subject:"Q3 planning" newer_than:1d を検索します。
2. reply_to_workspace_email — 返されたスレッド ID に、指定された本文で返信します。

応答（一部省略）：

{
  "thread": {
    "id": "1928a...",
    "subject": "Q3 planning",
    "from": "[email protected]"
  },
  "reply": {
    "id": "1928b...",
    "labelIds": ["SENT"]
  }
}

要件

• Node.js 20+（engines.node は >=18 ですが、ビルドとテストは 20 および 22 で実行しています）
• npm
• Google OAuth フローを実行し、コネクターが読み取る accounts.json とアカウントごとのトークンファイルを書き込むホストアプリケーション。

クイックスタート

インストールとビルド

cd <path-to-repo>/connectors/google-workspace
npm install
npm run build

npx（公開後）

npx -y @mindstone/mcp-server-google-workspace

ローカル

node dist/index.js

設定

このサーバーは、独自に Google OAuth フローを実行するホストアプリケーションと連携して動作するように設計されています。ホストは認証情報をディスクに書き込み、このサーバーはそれを読み取ります。

必須環境変数

変数	説明
GOOGLE_CLIENT_ID	Google OAuth クライアント ID。
GOOGLE_CLIENT_SECRET	Google OAuth クライアントシークレット。
ACCOUNTS_PATH	accounts.json へのパス（認証済みアカウントの一覧を記録した、ホストが書き込むインデックス）。
CREDENTIALS_PATH	アカウントごとの Google OAuth トークンファイルを格納するディレクトリ。

オプションの環境変数

変数	デフォルト	説明
GOOGLE_WORKSPACE_REQUEST_TIMEOUT_MS	60000	Google API への送信リクエストのタイムアウト（ミリ秒）。最大値は 300000（5 分）です。

ホストによって GOOGLE_WORKSPACE_DISABLE_REFRESH=1 が設定されると、コネクターはトークンを更新せずに auth_required を返します。これは、ユーザー向けのセットアップ変数ではありません。

認証フロー

authenticate_workspace_account は、構造化された auth_required レスポンスを返します。

{
  "status": "auth_required",
  "user_action": { "id": "google.connect_account" },
  "agent_action": {
    "instruction": "Connect Google Workspace to continue. The user will be redirected to Google's sign-in."
  },
  "setupToolName": "authenticate_workspace_account"
}

コネクターはコールバックサーバーを起動せず、OAuth URL も生成しません。MCP ホストが Google OAuth URL を計算し、コールバックを処理します。ホストがアカウントのトークンファイルを CREDENTIALS_PATH/ に、エントリーを ACCOUNTS_PATH に書き込むと、次のツール呼び出しは成功します。

ホスト設定の例

Claude Desktop / Cursor

{
  "mcpServers": {
    "GoogleWorkspace": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-google-workspace"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-google-oauth-client-id",
        "GOOGLE_CLIENT_SECRET": "your-google-oauth-client-secret",
        "ACCOUNTS_PATH": "/absolute/path/to/accounts.json",
        "CREDENTIALS_PATH": "/absolute/path/to/credentials"
      }
    }
  }
}

ホストが ${ACCOUNTS_PATH} と、対応するアカウントごとのトークンファイルを ${CREDENTIALS_PATH}/ に書き込むまでは、すべてのツール呼び出しで構造化された auth_required レスポンスが返されます（上記の「認証フロー」を参照）。

ローカル開発（npm への公開は不要）

{
  "mcpServers": {
    "GoogleWorkspace": {
      "command": "node",
      "args": ["<path-to-repo>/connectors/google-workspace/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-google-oauth-client-id",
        "GOOGLE_CLIENT_SECRET": "your-google-oauth-client-secret",
        "ACCOUNTS_PATH": "/absolute/path/to/accounts.json",
        "CREDENTIALS_PATH": "/absolute/path/to/credentials"
      }
    }
  }
}

ツール（124）

全ツールの一覧は src/tools/definitions/ にあり、tools-inventory.json にも掲載されています。ドメイン別の内訳は次のとおりです。

ドメイン	ツール数	備考
Gmail	23	メールの検索、スレッドの検索、送信、作成、下書き、ラベル、ラベルフィルター、添付ファイル、アーカイブ／ゴミ箱への移動／既読状態の補助機能、設定、不在通知、自分のアドレスとして送信するエイリアスと署名。
Calendar	9	現在時刻、空き時間の検索、カレンダー／イベントの一覧表示、イベントの作成、更新、返信、削除。
Drive	15	ファイルやフォルダーの一覧表示、検索、アップロード、ダウンロード、コピー、移動、ゴミ箱への移動、ゴミ箱からの復元、権限、リビジョン、共有ドライブの検出、アクティビティの照会（何が、いつ、誰によって変更されたか）。
Docs	13	読み取り、作成、追記、置換、検索と置換（ドキュメント全体または 1 つのタブ）、アンカー位置へのテキスト挿入、タブツリーの取得、タブの追加／名前変更／移動／削除、あるタブの内容の別のタブへのコピー、一括更新。読み取り、追記、置換、検索と置換では、1 つのタブ（tab_id）を対象にできます。読み取りでは、すべてのタブ（all_tabs）も対象にできます。
Sheets	17	範囲の読み取り／書き込み、スプレッドシートの作成、シートの管理（追加、複製、名前変更、並べ替え、削除）、隣接する行や列と同じ書式での行または列の挿入、一括操作、検索と置換、書式設定。
Slides	7	読み取り、作成、スライドの一覧表示／取得、一括更新、サムネイル、ID の抽出。
Labels	12	Gmail のラベルの CRUD とフィルタールール。
Contacts	4	連絡先の一覧表示、検索、作成、更新。
Chat	3	スペースの一覧表示、スペース内のメッセージの一覧表示、テキストメッセージの送信。
Meet	3	会議の記録の一覧表示、文字起こしの一覧表示、文字起こしの項目（話者＋テキスト）の読み取り。
Comments	5	Drive コメントの一覧表示、作成、返信、解決、削除。
Account	3	Workspace アカウントの一覧表示、認証、削除。
Tasks	6	タスクリストの一覧表示、タスクの一覧表示、作成、更新、完了、削除。
Forms	4	フォームとその回答への読み取り専用アクセス。

共有ドライブ

すべての Drive のファイル、権限、コメントのツールは共有ドライブ内のファイルでも機能します（files.* と permissions.* の呼び出しでは supportsAllDrives が渡されます。Comments API はファイル ID でファイルを指定し、そのようなフラグは定義されていません）。一覧表示と検索では、デフォルトでユーザー自身のコーパスと共有されているファイルが対象になります。そのため、ユーザーがアクセスできても一度も開いたことのない共有ドライブのコンテンツは、デフォルトでは表示されないことがあります。共有ドライブを明示的に操作するには、次のようにします。

• ドライブを探す： list_shared_drives は、アカウントがアクセスできる共有ドライブを返します（ID、名前、作成時刻）。
• 特定のドライブを対象にする： list_drive_files ／ search_drive_files に options.driveId を渡します。driveId が設定されている場合、コネクターは corpora: 'drive' を強制します（Drive API は他の組み合わせを拒否するため）。呼び出し元が指定した corpora は上書きされます。
• すべてを検索する： options.corpora: 'allDrives' を渡すと（driveId は指定しません）、1 回のクエリでマイドライブとすべての共有ドライブを検索できます。Google は、対象を絞った検索でのみこの方法を推奨しています。閲覧する場合は、特定の driveId を指定してください。

共有ドライブのファイルに関する既知の Drive API の制限（このコネクターでは解決できません）：

• 共有ドライブに属するファイルには owners[] がありません。所有権はドライブ自体に属します。ファイルの帰属を判断する際は、代わりに lastModifyingUser と createdTime を使用してください。
• Revisions API は共有ドライブのファイルに対応していないため、list_file_revisions ／ download_file_revision はマイドライブのファイルでのみ機能します。

Docs のタブ

Google Doc には多数のタブを含めることができ、数階層まで入れ子にできます。各タブには t.abc123 のようなタブ ID があります。list_workspace_document_tabs は各タブの ID、親、位置を含むツリー全体を表示します。?tab=t.xxxx を含む Docs のリンクは特定のタブを指し、t.xxxx がそのタブ ID です。

tab_id を指定しない場合：

• read_workspace_document は最初のタブを返します。複数のタブがあるドキュメントでは、タブの数を示す行も追加されます。特定のタブを読むには tab_id を、すべてのタブを ## Tab: 見出しの下に読み取るには all_tabs: true を渡します。すべてのタブで共有する max_chars の上限が適用され、上限に収まらないタブは ID で一覧表示されます。
• append_to_workspace_document、replace_workspace_document、insert_workspace_document_text は最初のタブを操作します。ツールの呼び出しで、以前の呼び出しで使ったタブが引き継がれることはありません。そのため、別のタブを操作する呼び出しでは毎回 tab_id を渡してください。
• find_and_replace_workspace_document はすべてのタブで置換します。1 つのタブに限定するには tab_id を渡します。そのサブタブは別のタブであり、置換対象には含まれません。

tab_id: "default" は、読み取り、編集、アンカー付き挿入、タブ追加時の parent_tab_id、およびコピー元における最初のトップレベルのタブを意味します。タブの削除、名前変更、移動、上書きを行うツールには実際のタブ ID が必要で、"default" は拒否されます。

タブの管理： add_workspace_document_tab、update_workspace_document_tab（名前変更、順序変更、または別のタブの下へのネスト。API ではサブタブをトップレベルに戻すことはできません）、delete_workspace_document_tab。

• サブタブを含め、タブ名はドキュメント全体で一意である必要があります。重複がある場合は、変更を加える前に拒否されます。
• position はタブの兄弟間での 0 始まりの位置（0 = 先頭）で、移動後のタブの位置を表します。一覧表示での番号は 1 から始まります。結果には、ドキュメント上で実際に表示される位置が報告されます。
• タブを削除すると、そのサブタブもすべて削除されます。サブタブを持つタブは、delete_sub_tabs: true が渡されない限り削除を拒否されます。 アンカーへのテキスト挿入： insert_workspace_document_text は、書き換えることなく、1 つのタブにプレーンテキストを追加します。anchor_text はタブ内の 1 つの段落に、完全一致で 1 回だけ含まれている必要があります。position は、アンカーのafter（デフォルト）またはbefore、あるいは next_paragraph_start（アンカーがある段落の次の段落の先頭）です。これは見出しの下にある空の箇条書きに入力する場合に使用します。その位置の直前の行をアンカーにしてください。その段落は、expect_empty_paragraph: false を指定しない限り、空である必要があります。改行は新しい段落を作成し、見出しまたは箇条書きの段落書式を引き継ぎます。挿入されるテキスト自体はプレーンテキストで、前後のテキストから太字やリンクを引き継ぐことはありません。

タブのコピー： copy_workspace_document_tab は、1 つのタブの内容を同じドキュメント内の別のタブにコピーします。

• コピーされるもの：テキスト、見出しと段落のスタイル、文字スタイルとリンク、箇条書きと番号付きリスト（Google Docs の既定のリストスタイルに変換）、表（セルのテキスト、列幅、セルスタイル）、改ページ、スマートチップ。開くことができないファイルへのリンクを含むスマートチップは、タイトル付きリンクになります。ユーザーと日付のチップはテキストになります。結果には両方が一覧表示されます。
• コピーされないもの：ヘッダーとフッター、サブタブ、画像およびその他の特殊要素（「Not copied」に一覧表示されます。インラインのものは、見える [placeholder] も残します）、表セルの結合（セルは結合されていない状態でコピーされます。結合セルをコピーできない表は、何も書き込まれる前に拒否されます）。
• 正確にはコピーされないもの：コピーしたタブ内の見出しへのリンクは、元のタブの見出しを指したままになります。そのため、リセット後はリンク先が解決されなくなります。
• コピー先の指定方法：タブをアーカイブまたは複製するには、new_tab_title を使用します。テンプレートタブからタブをその場でリセットする（ID、位置、サブタブを維持する）には、target_tab_id と overwrite_existing: true を指定します。これにより、対象のタブが最初にクリアされます。置き換えるためにタブを削除しないでください。削除すると、そのサブタブも削除されます。
• 結果の先頭には、テキスト、見出しの種類、段落書式、箇条書き、リストのグループ化、表の形状をコピー元と比較する Verification: 行が表示されます。コピー元を削除またはリセットする前に、passed と表示されていることと、失う可能性のあるものが「Not copied」行に記載されていないことの両方を確認してください。たとえば、フローティング画像が除外されていても、検証に合格することがあります。検証に失敗した場合は、エラー結果が返されます。
• コピーはアトミックではありません。途中で停止した場合、コネクタは新しいタブの削除を再試行し、その結果が表示されます（削除できなかった場合は、削除するタブの名前が示されます）。既存のコピー先は、クリアされた状態または一部だけ書き込まれた状態になることがあります（ドキュメントのバージョン履歴から復元できます）。コピーが完了しても検証で差異が見つかった場合は、確認できるようにタブが保持され、差異がある最初の数か所が結果に一覧表示されます。長いタブでは 10～60 秒かかることがあります。

週次のアーカイブとリセットの例： ライブタブと Template タブがある架空の「Acme weekly sync」ドキュメントを使用します。ビジネスルール（次回会議の日付、残す行）は呼び出し元が指定します。

1. list_workspace_document_tabs を実行して、現在のタブとテンプレートのタブ ID を取得し、tab_id: <live tab id> を指定して現在のタブを読み取ります。変更を加える前に、日付の行と不在時の行を確認しておきます。
2. copy_workspace_document_tab を実行し、source_tab_id: <live tab id>、new_tab_title: "2031-10-13"、new_tab_parent_id: <live tab id>、new_tab_position: 0 を指定して、最初のサブタブとしてアーカイブします。
3. 結果に Verification: passed と表示され、アーカイブに不要なものが Not copied の行に何も記載されていない場合を除き、停止します。
4. copy_workspace_document_tab を実行し、source_tab_id: <Template tab id>、target_tab_id: <live tab id>、overwrite_existing: true を指定して、現在のタブをその場でリセットします。
5. 日付のプレースホルダーを find_and_replace_workspace_document で置換します。tab_id: <live tab id> を指定してください（指定しないと、テンプレートのプレースホルダーも変更されます）。結果に Replaced 1 と表示されることを確認します。
6. 不在時の行を insert_workspace_document_text で挿入します。tab_id: <live tab id> と position: "next_paragraph_start" を指定し、空の箇条書きの直前の行を基準にします（指定しないと、最初のタブにテキストが挿入されます。最初のタブがテンプレートの場合もあります）。

休暇中の自動返信

update_workspace_vacation_responder は既存の設定にマージします（Gmail API は、指定がない限りリソース全体を置き換えます）。省略した件名と本文は保持され、既存の HTML 本文は HTML のまま維持され、end_time を省略すると、設定済みの終了日時も保持されます。終了日時の設定を削除して自動返信を無期限にするには、clear_end_time: true を渡します（end_time との併用はできません）。再度有効にする際、すでに過去になった終了日時は引き継がれません。

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

• トークンとアカウント情報の書き込みでは、一時ファイルへの書き込み後のリネーム、制限付きアクセス許可、fsync、シンボリックリンクの拒否を行います。
• ホスト側でトークンの更新を無効にして、リフレッシュトークンのローテーションを単一の主体が管理できます（GOOGLE_WORKSPACE_DISABLE_REFRESH=1）。
• ユーザーが復旧可能なエラーでは、action_required フィールドと next_step フィールドを含む、ホストに依存しない復旧ガイダンスを返します。
• 同梱のコールバックサーバーは削除されました。OAuth URL とコールバック処理は MCP ホスト側で行います。
• 添付ファイル名をサニタイズし、細工された upload_workspace_attachment のファイル名引数を介したパストラバーサルを防ぎます。
• <untrusted-content> エンベロープは、Contacts、Calendar、Comments、Forms、Tasks、および JSON を返すパスを対象としています。

ライセンス

FSL-1.1-MIT — Functional Source License, Version 1.1。MIT の将来ライセンスが付属します。このソフトウェアは 2030-04-08 に MIT ライセンスへ移行します。