Google Workspace MCP Server

---

なぜ？

gws CLI に組み込まれていた MCP サーバーは、200～400 個のツールを公開し、MCP クライアントのコンテキストウィンドウを肥大化させるため、v0.8.0 で削除されました。このサーバーでは厳選されたアプローチを採用しています。公開する Google サービスを選択でき、価値が高く用途を絞った操作だけをツールとして登録します。各ツールでは、4 つすべての MCP アノテーションヒント（readOnlyHint、destructiveHint、idempotentHint、openWorldHint）を宣言するため、クライアントは副作用を判断し、どの書き込み操作を安全に再試行できるかを把握し、より明確な同意プロンプトを表示できます。これは、エージェントの信頼性を支えるインフラストラクチャにおける権限面です。意図的に狭めたツールの範囲、すべてのツールで宣言される副作用、そして単独の送信ツールはありません。エージェントが実行できる唯一のメール送信は、カレンダーの招待や更新通知です。これは sendUpdates によるオプトイン方式で、デフォルトでは無効です。

前提条件

• Node.js 18+
• gws CLI のインストールと認証（npm install -g @googleworkspace/cli && gws auth login）

デフォルトより少ないスコープを付与する

このサーバーには単独で使える送信ツールはありません。gmail_drafts_create は明示的に送信を行わず、エージェントがトリガーできる唯一の送信メールは、sendUpdates を介したカレンダーの招待状／更新通知です。sendUpdates は列挙値で検証され、デフォルトは none です。gws auth login が発行するトークンは、それよりも広い権限を持ちます。

gws auth login を実行すると、9 個のスコープを一覧表示するスコープ選択画面が開きます。デフォルトで付与されるのは7 個です。読み書きが可能な drive、spreadsheets、gmail.modify（Google の説明では「メールの閲覧、作成、送信」）、calendar、documents、presentations、tasks です。これは、非対話型で DEFAULT_SCOPES を使った場合に付与される 7 個と同じです。

残りの 2 行は Cloud Pub/Sub と Cloud Platform で、どちらもデフォルトの付与対象には含まれません。gws auth login --help では、--full は「pubsub と cloud-platform を含むすべてのスコープをリクエストする」と説明されています。

どの行に最初からチェックが入っているかは、実際の選択画面で確認されていません。上記の 7 個は、ドキュメントに記載されたデフォルトの付与対象であり、TUI で確認されたものではありません。この説明を鵜呑みにせず、Enter キーを押す前にチェックボックスを確認してください。

そのため、ここでは何もしなくても、ディスク上のトークンでメールを送信したり、Drive の内容を書き換えたりできます。選択画面で必要のないスコープの選択を解除してください。または、次のようにします。

gws auth login --readonly    # read-only across services

-s gmail は、フラグのヘルプ文（「スコープ選択画面の対象を限定する、カンマ区切りのサービス名」）にあるとおり、選択画面を Gmail に限定します。cloud-platform や pubsub を追加することはできません。これら 2 つは --full からのみ利用できます。また、既存の認証情報に追加するのではなく、置き換えます。既存のログインにサービスを追加するには、gws-mcp-server auth login を使用してください。

Linux にはキーリングがなく、暗号化キーは暗号化対象のデータと同じ場所にあるファイルに保存されます。 gws は、keyring クレートのネイティブバックエンドを macOS と Windows でのみ有効にします。それ以外のすべてのプラットフォームでは、バックエンド機能なしで依存関係が宣言されるため、ストアは最終的に ~/.config/gws/ へ .encryption_key を書き込みます。このファイルは、別の場所にあるキーのバックアップではありません。これ自体がキーであり、認証情報ストアのドキュメントコメントには、決して削除されないと記載されています。GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file を設定しても、もともとこれが唯一の保存方法であるため、何も変わりません。macOS と Windows では、OS のキーリングにキーが保存されると、キーファイルは削除されます。Linux でヘッドレス実行する場合は、~/.config/gws/ をパスワードファイルとして扱ってください。このディレクトリを読み取れる人は、認証情報も読み取れます。

Contacts にはデフォルトの許可範囲外のスコープが必要です

people_* ツールには contacts スコープが必要です。デフォルトの gws auth login（および上記で説明した7つのスコープの許可）ではリクエストされません。

Contacts を追加するには、gws auth login -s people ではなく gws-mcp-server auth login -s people を実行してください。 gws のフィルター付きログインは、保存済みの認証情報をフィルター後のスコープだけで置き換えるため、Drive、Gmail、Calendar など、これまでに許可したほかのすべてのスコープが削除されます（#68、上流の googleworkspace/cli#673 で追跡中）。このサーバーの auth login では、代わりに段階的な認可を行います。

gws-mcp-server auth login -s people              # keep existing scopes, add contacts
gws-mcp-server auth login -s people --dry-run    # print the gws command first

保存済みの認証情報が持つスコープを gws auth status から読み取り、指定したサービスのスコープを追加して、gws auth login --scopes <existing + new> を実行します。ブラウザーで一度同意すれば完了です。その後、gws auth status を再度読み込み、要求したスコープ（既存・新規を問わず）が許可されなかった場合、たとえば Google の同意画面でチェックボックスがオフにされた場合は、ゼロ以外の終了コードで終了します。gws は同意画面で許可された内容を保存するため、チェックボックスをオフにすると、そのスコープは保存済みの認証情報から削除されます。ブラウザーを開く前と、完了後に不足が見つかった場合に、要求したすべてのスコープを再度リクエストする gws auth login --scopes "..." コマンドを表示します。あらかじめ gws auth login 用のクライアントが設定されている必要があります。また、認証情報がすでに対象サービスをカバーしている場合は、何も変更せずに終了します。

フラグ	効果
--services, -s <list>	スコープを追加するサービス（必須）
--readonly	各サービスの読み取り専用スコープを追加します（読み書きスコープをすでに持っている場合は追加しません）
--dry-run	実行せずに gws auth login コマンドを表示します
--replace	従来の動作です。認証情報を要求したスコープだけで置き換えます
--gws-path <path>	gws バイナリ。サーバーフラグと同じです

gws auth status はスコープをリアルタイムで検出するため（リフレッシュトークンの交換と Google のトークン情報の照会）、失敗時には scopes フィールドが欠落することがあります。保存済みの認証情報が存在するものの、そのスコープを読み取れない場合、auth login は推測せずに処理を拒否します。ステータスの照会を修正してから再試行してください。要求したスコープだけで最初からやり直す場合は、--replace を指定してください。保存済みの認証情報がない場合は初回ログインとなり、指定したサービスだけがリクエストされます。

gws を直接実行する場合は、完全なスコープ一覧を自分で指定してください。上記で説明したデフォルトの7つのスコープを使った認証情報の場合は、次のとおりです。

gws auth login --scopes "https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/documents,https://www.googleapis.com/auth/presentations,https://www.googleapis.com/auth/tasks,https://www.googleapis.com/auth/contacts"

また、OAuth とは別に、自分の GCP プロジェクトで People API を有効にする必要があります。新しいスコープを許可しても、新しい API が自動的に有効になるわけではないため、これは一度だけ行う必要があります。

gcloud services enable people.googleapis.com --project=<your-project-id>

両方の手順を行わないと、people_* ツールは失敗します。スコープが不足している場合は Google から 401／403 が返され、API が無効な場合は、API 名と有効化用のコンソールリンクを示す別の 403 が返されます。

クイックスタート

# Install
npm install -g gws-mcp-server

# Or run from source
git clone https://github.com/conorbronsdon/gws-mcp-server.git
cd gws-mcp-server
npm install && npm run build

設定

Claude Code（.mcp.json）

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": [
        "gws-mcp-server",
        "--services", "drive,sheets,calendar,docs,slides,gmail,tasks"
      ]
    }
  }
}

Contacts は追加の認証と API 設定が必要なため、オプトイン方式です。 Contacts の前提条件を完了した後、サービス一覧に people を追加してください。

"args": ["gws-mcp-server", "--services", "drive,calendar,people"]

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": [
        "gws-mcp-server",
        "--services", "drive,sheets,calendar"
      ]
    }
  }
}

オプション

フラグ	説明	デフォルト
--services, -s	公開するサービスのカンマ区切りリスト	コアサービス。people はオプトイン
--gws-path	gws バイナリへのパス	GWS_BINARY または gws
--read-only	読み取り専用ツールのみ登録します	オフ

Windows では、npm の gws.cmd は JavaScript のエントリーポイントとして解決され、Node で実行されます。--gws-path または GWS_BINARY には、JavaScript のエントリーポイントや .exe を直接指定することもできます。

--read-only

--read-only では、デフォルトの 61 個ではなく26 個のツールが登録されます。Google に書き込みを行うツールはすべて登録されないため、tools/list に表示されず、エージェントが呼び出せるものはありません。送信を行わなくても書き込みに該当する gmail_drafts_create も含まれます。読み取りを行う drive_files_download は登録されたままです。people を明示的に追加すると、合計 67 個のうち読み取り専用ツールは 29 個になります。

gws-mcp-server --read-only
gws-mcp-server --read-only --services drive,calendar   # combines with -s

これは認証情報ではなくエージェントを制約します。ディスク上のトークンには付与されたスコープがそのまま残り、マシン上のほかのものは引き続き使用できます。トークンの範囲を狭めるのは gws auth login --readonly です。この 2 つは相互に補完するものです。MCP サーバーではエージェントが脅威モデルですが、この主張には限界があります。

コンテキストコストの削減

登録されたすべてのツールは、会話ごとに含まれます。デフォルトのレジストリは、およそ 46 KB の tools/list ペイロード（約 11.8K トークン）です。people を追加すると、レジストリ全体はおよそ 52 KB（約 13.2K トークン）になります。上記の 2 つのフラグは組み合わせて使用できます。使用しないサービスを丸ごと除外するのが、コンテキストを最も手軽に節約する方法です。

gws-mcp-server --services calendar                       # calendar assistant: 6 tools
gws-mcp-server --services drive,docs                     # document work, nothing else
gws-mcp-server --read-only --services drive,docs,sheets  # research setup: reads only

.mcp.json または claude_desktop_config.json では、args 配列を編集するだけで同じように絞り込めます。

"args": ["gws-mcp-server", "--services", "drive,calendar"]

サービスのツール数（以下の見出しに記載）は、そのコンテキストコストの目安になります。drive（24 個のツール）を除外すると最も大きく節約でき、docs（3 個のツール）を除外した場合は最小限の節約になります。現時点ではツール単位の除外フラグはありません。サービス単位の粒度が用途に合わない場合は、必要な分割を説明してイシューを作成してください。

利用可能なサービスとツール

drive（24 個のツール）

• drive_files_list — ファイルを検索して一覧表示します
• drive_files_get — ファイルのメタデータを取得します
• drive_files_create — ファイルを作成します（アップロードは任意）
• drive_files_copy — ファイルをコピーします（形式変換に便利です）
• drive_files_update — ファイルのメタデータや内容を更新します
• drive_files_delete — ファイルを削除します
• drive_files_export — Google Workspace のファイル（Doc、Sheet、Slide）を別の形式にエクスポートします
• drive_files_download — ファイルの内容をダウンロードします（テキストはインラインで、バイナリは base64 で返すか、パスに保存します。Google ネイティブファイルは読み取り可能な形式にエクスポートされます）
• drive_permissions_create — ファイルを共有します
• drive_permissions_list — ファイルのすべての権限を一覧表示します（公開アクセスの有無など、共有状態の監査に使用します）
• drive_permissions_update — 既存の権限のロールを変更します（例：閲覧者から編集者へ）。権限を下げると機能が制限されます。所有権の変更には、以下の専用ツールを使用してください。
• drive_permissions_delete — ファイルの権限を取り消します
• drive_permissions_transferOwnership — 同じ組織内の別の Google Workspace アカウントへ、ただちに所有権を移転し、現在の所有者を編集者に降格させます。必須の通知メールが送信されます。共有ドライブのファイルには対応していません
• drive_permissions_proposeOwnershipTransfer — 個人アカウント間での所有権の移転を提案します。受取人は別途承諾する必要があります（必須のメール通知が送信されます）。これだけでは所有権は移転しません
• drive_comments_list — ファイルのコメントを一覧表示します（Docs／Sheets／Slides に限らず、あらゆる Drive ファイルで使用できます）
• drive_comments_get — 個別のコメントを取得します
• drive_comments_create — コメントを追加します。アプリで定義した領域に任意で固定できます（ただし、Workspace エディターでは固定されていないコメントとして表示されます）
• drive_comments_update — コメントのテキストを変更します（作成者のみ）
• drive_comments_delete — コメントを完全に削除します（作成者のみ）
• drive_replies_list — コメントへの返信を一覧表示します
• drive_replies_get — 個別の返信を取得します
• drive_replies_create — コメントに返信するか、action フィールドで解決または再開します
• drive_replies_update — 返信のテキストを変更します（作成者のみ）
• drive_replies_delete — 返信を完全に削除します（作成者のみ）

sheets（5 個のツール）

• sheets_get — スプレッドシートのメタデータを取得
• sheets_values_get — セルの値を読み取る
• sheets_values_update — セルの値を書き込む
• sheets_values_append — 行を追加
• sheets_batchUpdate — スプレッドシートに更新を適用（条件付き書式、セル／罫線の書式設定、シートの追加など。削除リクエストは取り消せません）

calendar（6 個のツール）

• calendar_events_list — 予定の一覧を取得
• calendar_events_get — 予定の詳細を取得
• calendar_events_insert — 予定を作成（任意で attendees を指定できます）。sendUpdates は招待メールを送信するかどうかを制御します（デフォルトは none — メールは送信されませんが、参加者の設定によっては予定が参加者のカレンダーに表示される場合があります）
• calendar_events_update — 予定を更新（指定したフィールドのみが変更されます。ただし、attendees はリスト全体を置き換えるため、省略された参加者は招待が取り消されます）。insert と同じ sendUpdates に対応しています
• calendar_events_delete — 予定を削除
• calendar_freebusy_query — 指定した期間について、1 つ以上のカレンダーの空き時間情報を照会

docs（3 個のツール）

• docs_get — ドキュメントの内容を取得
• docs_create — ドキュメントを作成
• docs_batchUpdate — ドキュメントに更新を適用

slides（5 個のツール）

• slides_get — プレゼンテーションのスライド、レイアウト、マスター、ページ要素を取得
• slides_create — 空のプレゼンテーションを作成
• slides_batchUpdate — 更新を適用（スライド、テキスト、図形、表などの挿入／更新／削除）
• slides_pages_get — 単一のページ（スライド、レイアウト、またはマスター）を取得
• slides_pages_getThumbnail — ページのサムネイル画像の URL を取得

gmail（6 個のツール）

• gmail_messages_list — メッセージを検索
• gmail_messages_get — メッセージを読み取る
• gmail_threads_list — スレッドを検索
• gmail_threads_get — スレッド全体を読み取る
• gmail_threads_modify — スレッドのラベルを追加／削除（アーカイブ、既読にする、スターを付ける）
• gmail_drafts_create — 下書きを作成（プレーンテキストおよび／または HTML。threadId を使った返信スレッドに対応）。下書きが自動送信されることはありません

tasks（12 個のツール）

• tasks_tasklists_list — タスクリストの一覧を取得
• tasks_tasklists_get — タスクリストを取得
• tasks_tasklists_insert — タスクリストを作成
• tasks_tasklists_update — タスクリストを更新（指定したフィールドのみ変更）
• tasks_tasklists_delete — タスクリストを削除
• tasks_tasks_list — タスクの一覧を取得（完了／非表示／期限日で絞り込み）
• tasks_tasks_get — タスクを取得
• tasks_tasks_insert — タスクを作成（任意でネストまたは配置できます）
• tasks_tasks_update — タスクを更新（指定したフィールドのみ変更。よく使われる用途：完了にする）
• tasks_tasks_move — リスト内またはリスト間でタスクを移動、または順序を変更
• tasks_tasks_delete — タスクを削除
• tasks_tasks_clear — リスト内の完了済みタスクをすべて非表示にする

people（6 個のツール）

contacts スコープと People API の有効化が必要です。Contacts needs a scope outside the default grant を参照してください。

• people_people_get — リソース名で連絡先を取得（または認証済みユーザーには people/me を指定）
• people_people_searchContacts — 名前、メールアドレス、電話番号、または組織で連絡先を検索
• people_people_createContact — 新しい連絡先を作成
• people_people_updateContact — 連絡先を更新（リクエスト本文に現在の etag が必要です）
• people_people_deleteContact — 連絡先を完全に削除
• people_connections_list — 認証済みユーザーの連絡先一覧を取得

更新の動作： *_update ツール（カレンダーの予定、タスク、タスクリスト）は、Google API の patch 動詞を使用します。指定したフィールドをマージし、それ以外は変更しません。既存の値をクリアするには、省略するのではなく、空文字列などを明示的に渡してください。

合計：サポート対象のツールは 67 個、デフォルトで有効なツールは 61 個（旧実装の 200～400 個に対して）

新しいツールの追加

ツール定義を追加するには、src/services.ts を編集します。各ツールは gws CLI コマンドに直接対応します。

{
  name: "drive_files_list",           // MCP tool name
  description: "List files in Drive", // Shown to AI
  command: ["drive", "files", "list"],// gws CLI args
  params: [                           // Maps to --params JSON
    { name: "q", description: "Search query", type: "string", required: false },
  ],
  bodyParams: [                       // Maps to --json body
    { name: "name", description: "File name", type: "string", required: true },
  ],
}

型付きエラー

ツール呼び出しの失敗は、型付きエラー階層（src/errors.ts）にマッピングされます。AuthenticationError（401／403）、RateLimitError（429）、ValidationError（400）、NotFoundError（404。drive コマンドでは共有ドライブへのアクセスに関するヒントを含みます）、ServerError（5xx）があり、いずれも基底クラスの GwsError を継承します。HTTP API クライアントとは異なり、このサーバーにはステータスコードを読み取れるレスポンスオブジェクトがありません。gws CLI をサブプロセスとして起動し、プレーンテキスト（stdout／stderr、または拒否された Promise の .message）のみを受け取るためです。mapGwsErrorToTyped() は、テキストからステータスコードに相当する値を復元します。生の JSON エラーボディ（Google 独自の {"error":{"code":...,"message":...}} 形式）と、HTTP ステータスコードに似たトークンを含むプレーンテキスト（例："Error 404: ..."）の両方に対応しています。どちらのパターンも見つからない場合は、根拠のないステータスを割り当てず、元のメッセージをそのまま返します。

アーキテクチャ

MCP Client (Claude) ←→ stdio ←→ gws-mcp-server ←→ gws CLI ←→ Google APIs

このサーバーは薄いラッパーです。MCP ツール呼び出しを gws CLI の実行に変換し、必要に応じて --params と --json を渡して、JSON 出力を返します。認証は gws CLI が担います。このサーバーが Google の認証情報を参照したり保存したりすることはありません。

開発

git clone https://github.com/conorbronsdon/gws-mcp-server.git
cd gws-mcp-server
npm ci
npm run lint    # type-check
npm run build
npm test        # vitest, mocks the executor layer — no real gws calls

コントリビューション

イシューやプルリクエストを歓迎します。厳選された契約を維持してください。対象を絞った少数のツールを提供し、すべての Google API をそのまま 1 対 1 で反映するものではありません。新しいサービスの PR を作成する前に、ユースケース、必要なスコープ、副作用を説明したイシューを作成してください。docs/scope-policy.md では、ここに追加するものと、コンパニオンサーバーとして提供するほうが適しているものについて説明しています。既存のツールの改善は、直接歓迎します。脆弱性の報告方法については SECURITY.md をご覧ください。

コンパニオンサーバー

厳選された対象に含まれないサービスは、それぞれ独自のスコープ許可を持つ、個別の MCP サーバーとしてこのサーバーと並行して実行できます。すべてのツールで副作用を宣言し、単独で実行できる送信アクションを追加しないコミュニティのコンパニオンサーバーは、ここに掲載します。

その他の選択肢

このサーバーは意図的に対象を絞っています。厳選されたツール群を提供し、すべてのツールで副作用を宣言し、単独で実行できる送信ツールはありません。これは一部のワークフローには適切ですが、そうでないものもあります。実際の選択肢は次のとおりです。

希望すること	使用するもの
すべての Workspace API をセルフホストで利用し、階層化と複数ユーザー OAuth に対応する	taylorwilsdon/google_workspace_mcp — 12 のサービスにわたる 120 以上のツール、MIT、--tool-tier core|extended|complete
Google がホストする Google 独自のサーバーを利用する	Google Workspace remote MCP servers — 8 つのエンドポイント、42 のツール。デベロッパープレビュー：アプリケーション、Workspace アカウント（個人の Gmail ではありません）、および対応するクライアントプランが必要です
MCP は使わず、CLI とエージェントスキルを利用する	googleworkspace/cli — このサーバーと同じ gws auth login を使用する 100 以上の Agent Skills

はっきり述べておく価値があります。Google 公式の Gmail MCP サーバーも下書き専用で、送信ツールはありません。厳選されたツール群を提供するという主張は、もはや異端ではありません。このサーバーが今も他にはない形で提供しているものは、Google Tasks（Google 公式のラインアップには Tasks サーバーがありません）、すべてのツールに付与された 4 つの MCP アノテーションヒントすべて、プレビュー用アプリケーションやプランによる制限のないローカルの stdio サーバー、そして単一のフラグで指定できる --read-only です。

分析系の関連サーバー

データ	サーバー
Google Workspace	このリポジトリ
Search Console	gsc-mcp — 派生ビューの gsc_striking_distance などを含む、同様に厳選されたアプローチ
YouTube Analytics	yt-analytics-mcp — オーナー向けのチャンネル、動画、再生リストの指標。読み取り専用、ツールは9個
Google Analytics 4	googleanalytics/google-analytics-mcp — Google公式、読み取り専用
BigQuery	googleapis/mcp-toolbox — Google公式

これらは別々の認証情報であり、1つのログインを共有するものではありません。Workspace は gws auth login、Search Console は webmasters OAuth 認証情報、YouTube Analytics は yt-analytics.readonly OAuth 認証情報、GA4 は analytics.readonly スコープの Application Default Credentials で認証します。ここにあるもの同士でトークンを共有することはありません。

概要

Conor Bronsdon が開発・保守しています。私は、AI インフラ、開発者ツール、そして実務者がこれらを実際にどう活用しているかを取り上げるポッドキャスト、Chain of Thought を配信しています。番組運営に使うエージェントのワークフローから、Gmail、Calendar、Drive、Sheets、Docs、Slides、Tasks、Contacts への安全で厳選されたアクセスを実現するために、これを開発しました。

関連ツール：

• Transistor MCP：Transistor.fm公式のMCPサーバー。エピソード、公開、分析に対応しています。
• substack-mcp：Substackの記事の閲覧と下書きの管理に対応し、エージェントのワークフローでも安全に使えます。
• podcastindex-mcp：Podcast IndexのMCPサーバー。人物やトピックでの検索、トレンドの番組、フィードの健全性確認に対応しています。
• op3-mcp：OP3を通じたポッドキャスト分析。ダウンロード数、地域、アプリを確認できます。読み取り専用です。
• ai-tools-for-creators：アイデアを仕事にしている人向けに、AIスキルとMCPサーバーを厳選したリストです。

詳しくは chainofthought.show と X をご覧ください。

---

免責事項

これは個人による独立したプロジェクトであり、いかなる企業とも提携関係になく、スポンサー提供や承認も受けていません。ここで述べる見解はすべて個人のものです。

ライセンス

MIT