gws-connector

GWS Connector

複数アカウントに対応した Google Workspace MCP サーバー — 複数の Gmail、Google Calendar、Google Drive アカウントをスマートにルーティングして接続します。

Claude Code、Gemini CLI、GitHub Copilot、Cursor、OpenAI Codex、および MCP 互換クライアントで使用できます。

このサーバーを選ぶ理由

ほとんどの AI コーディングアシスタントがサポートする Google アカウントは 1 つだけです。複数の Google アカウント（個人用と仕事用、複数のクライアント、異なる組織など）を使用する場合、アカウントを手動で切り替える必要があります。この MCP サーバーを使えば、すべてのアカウントを一度に接続し、ラベル、メールアドレス、またはドメインでリクエストをルーティングできます。

機能

• 複数アカウント — Gmail と Google Workspace のアカウントを無制限に接続できます
• スマートルーティング — ラベル（work）、メールアドレス、またはドメインでアカウントを指定できます
• アカウントごとの OAuth — 組織ごとに独自の GCP 認証情報を使用できます
• 安全なストレージ — クライアントシークレットとトークンは OS のキーチェーンに保存されます（GNOME Keyring のない Linux ではファイルにフォールバックします）
• 49 個のツール — Mail（11）、Calendar（7）、Drive（3）、Sheets（8）、Docs（4）、Contacts（2）、Tasks（5）、Slides（3）、アカウント管理（6）
• アカウント管理 — アカウントの追加、削除、デフォルト設定、一覧表示ができます
• クロスプラットフォーム — 標準的な MCP サーバーとして、互換性のある任意のクライアントで動作します

他のサーバーとの比較

Google Workspace MCP サーバーには、優れたものがいくつかあります。複数アカウントと運用のシンプルさを重視するなら、GWS Connector がおすすめです。

Google アカウントを 1 つしか使わず、できるだけ幅広いツール（Forms、Chat、Vault、…）を利用したい場合は、taylorwilsdon/google_workspace_mcp のような単一アカウント用サーバーのほうが適しているかもしれません。GWS Connector は、複数アカウントの Gmail／Calendar／Drive／Sheets／Docs／Contacts／Tasks／Slides をシンプルかつ安全に扱うことに重点を置いています。

アップグレード（Google Tasks）

Google Tasks のツール（gws.tasks.*）は、新しい OAuth スコープ（tasks）を追加して提供されます。既存ユーザーは、接続済みの各アカウントを再認証する必要があります。これにより、このスコープを含む新しいトークンが発行されます。

/gws:reauth

ブラウザーの同意画面で承認する前に、新しいスコープで許可される内容を確認してください。アカウントの Google Tasks のリストとタスクへの読み取りおよび書き込みの完全なアクセス権が付与されます。詳細は、以下のスコープの理由の表を参照してください。

再認証の前に、GCP プロジェクトの OAuth 同意画面の設定で tasks スコープを追加し、Tasks API を有効にする必要があります。そうしないと、同意画面でリクエストが拒否されます。アカウントを再認証するまでは、gws.tasks.* ツールを実行すると、実行すべき再認証ツール名を示すスコープ不足エラーが返されます。

アップグレード — 連絡先 / People API

連絡先ツール（gws.contacts.search、gws.contacts.directory_search）に、読み取り専用の OAuth スコープが 2 つ（contacts.readonly、directory.readonly）追加されます。既存のユーザーは、各接続済みアカウントを再認証して、これらのスコープを含む新しいトークンを発行する必要があります。

/gws:reauth

ブラウザーの同意画面で承認する前に、新しいスコープで許可される内容を確認してください。Google Contacts と（Workspace アカウントの場合は）組織のディレクトリへの読み取り専用アクセスです。詳細は以下のスコープの理由に関する表をご覧ください。

再認証の前に、GCP プロジェクトの OAuth 同意画面の設定で People API を有効にし、新しいスコープを 2 つ追加する必要があります。そうしないと、同意画面でリクエストが拒否されます。gws.contacts.directory_search を利用するには Google Workspace アカウントが必要です。個人の Gmail アカウントには組織のディレクトリがないため、検索結果の代わりに分かりやすい説明メッセージが表示されます。

アップグレード（Google Slides ツール）

Slides ツール（gws.slides.*）に、新しい OAuth スコープ https://www.googleapis.com/auth/presentations が追加されます。既存のユーザーは、Slides スコープを含む新しいトークンを発行するため、各接続済みアカウントを再認証する必要があります。

/gws:reauth

再認証の前に、GCP プロジェクトの OAuth 同意画面の設定で Slides API を有効にし、presentations スコープを追加する必要があります。そうしないと、同意画面でリクエストが拒否されます（Google Cloud Setupをご覧ください）。再認証するまでは、gws.slides.* の呼び出しで、エージェントに gws.accounts.reauth の実行を促すスコープエラーが返されます。それ以外のツールは引き続き動作します。

v0.2.x からのアップグレード

v0.3.0 では、新しい OAuth スコープ（spreadsheets、documents）を使用するネイティブの Google Sheets ツールと Google Docs ツールが追加されます。既存のユーザーは、これらのスコープを含む新しいトークンを発行するため、各接続済みアカウントを再認証する必要があります。

/gws:reauth

ブラウザーの同意画面で承認する前に、新しいスコープで許可される内容を確認してください。該当アカウントの Google Drive にあるすべてのスプレッドシートとドキュメント（そのアカウントと共有されているファイルを含む）への完全な読み取りおよび書き込みアクセスです。詳細は以下のスコープの理由に関する表をご覧ください。

再認証の前に、GCP プロジェクトの OAuth 同意画面の設定で新しいスコープを 2 つ追加し、Sheets API と Docs API を有効にする必要があります。そうしないと、同意画面でリクエストが拒否されます。

クイックスタート（Claude Code）

1. プラグインをインストールする — Claude Code 内で次の 2 つのコマンドを実行します。

/plugin marketplace add orieg/gws-connector
/plugin install gws@gws-connector

2. Google Cloud の認証情報を設定する — 対話型ウィザードの案内に沿って設定します。

/gws:configure

これにより GCP プロジェクトが作成され、API が有効になり、最初のアカウントが接続されます。手動で設定する場合は、Google Cloud Setupをご覧ください。

3. 追加のアカウントを接続する：

/gws:add-account

アカウントごとに、異なる GCP プロジェクトの OAuth 認証情報を使用できます。

Gemini CLI

gemini extensions install https://github.com/orieg/gws-connector

バイナリは初回使用時に自動的にダウンロードされます。その後、Gemini 内でアカウントを接続します。

gws.accounts.add(label: "personal", clientId: "your-client-id", clientSecret: "your-secret")

その他のクライアント

git clone https://github.com/orieg/gws-connector && cd gws-connector && make build

gws.accounts.add(label: "personal", clientId: "your-client-id", clientSecret: "your-secret")

git clone https://github.com/orieg/gws-connector
cd gws-connector
make build
claude --plugin-dir ./

docker run -i --rm ghcr.io/orieg/gws-connector:latest

docker run -i --rm -v gws-state:/state -e GWS_STATE_DIR=/state \
  ghcr.io/orieg/gws-connector:latest

使用方法

すべての gws.* ツールでは、account パラメーターを省略できます。

# Uses default account
gws.mail.search(q: "is:unread")

# Target by label
gws.cal.list_events(account: "work")

# Target by email
gws.drive.search(account: "[email protected]", q: "quarterly report")

利用可能なツール

スキル

Claude Code と Gemini CLI の両方で利用できる対話型ワークフローです。

レシピ

アカウントを接続したら、アシスタントに自然な言葉で頼むだけです。適切なツールとアカウントが選ばれます。例：

• 複数アカウントをまたいだ朝の確認 — 「すべてのアカウントから過去 24 時間の未読メールをアカウントごとにまとめ、今日中に返信が必要なものに印を付けてください。」
• スレッドへの返信を下書きする — 「work アカウントで、Acme との Q3 請求書に関するスレッドを見つけ、新しい日付を確認する返信を下書きしてください。送信はしないでください。」
• メールをカレンダーの予定にする — 「イベントチームからの最新メッセージを読んで、そこに記載された日付と場所で、personal カレンダーに予定を作成してください。」
• アカウント横断の予定一覧 — 「仕事用と個人用のカレンダーで、明日はどんな会議がありますか？時系列で一覧にしてください。」
• ドキュメントを検索して要約する — 「client-acme の Drive で最新の『statement of work』を検索し、主な成果物と日付を教えてください。」
• スプレッドシートに記録する — 「個人用 Drive の『Expenses』シートに行を追加してください。今日の日付、『AWS』、42.50。」
• 受信トレイを整理する — 「personal アカウントで、newsletters@ からの未読メッセージすべてに『Newsletters』というラベルを付けて、既読にしてください。」

ヒント：

• アカウントのラベル（「work アカウントで」）、メールアドレス、またはドメインを指定して、対象のアカウントを明示できます。指定しない場合は、デフォルトのアカウントが使われます。
• 書き込み操作（下書き、予定、シートやドキュメントの編集）は、送信または変更する前にプレビューが表示され、確認を求められます。

Google Cloud の設定

初回のみの設定：

1. Google Cloud Console に移動し、新しいプロジェクトを作成します（例：「GWS Connector」）。

2. API を有効にする — 各リンクをクリックし、「有効にする」をクリックします：

   • Gmail API
   • Calendar API
   • Drive API
   • Sheets API
   • Docs API
   • People API
   • Tasks API
   • Slides API

3. OAuth 同意画面 を設定します：

   • 「外部」を選択します（Google Workspace 組織の場合は「内部」）。
   • アプリ名（例：「Claude GWS」）とサポート連絡先のメールアドレスを入力します。
   • 「保存」をクリックします。

4. スコープを追加 — データアクセス に移動します：

   • 「スコープを追加または削除」をクリックします。
   • 次の 11 個のスコープを追加します（「スコープを手動で追加」ボックスに貼り付けます）：
     • https://www.googleapis.com/auth/gmail.modify
     • https://www.googleapis.com/auth/calendar
     • https://www.googleapis.com/auth/drive
     • https://www.googleapis.com/auth/spreadsheets
     • https://www.googleapis.com/auth/documents
     • https://www.googleapis.com/auth/contacts.readonly
     • https://www.googleapis.com/auth/directory.readonly
     • https://www.googleapis.com/auth/tasks
     • https://www.googleapis.com/auth/presentations
     • https://www.googleapis.com/auth/userinfo.email
     • https://www.googleapis.com/auth/userinfo.profile
   • 「更新」をクリックし、「保存」をクリックします。

   各スコープが要求される理由：

   スコープ	目的	ツール
   gmail.modify	メッセージとラベルの読み取り、下書き作成、変更	gws.mail.*
   calendar	イベントの読み取り、作成、更新	gws.cal.*
   drive	Drive 全体のファイルとメタデータの検索と読み取り	gws.drive.*
   spreadsheets	Google Sheets のセルデータとメタデータの読み取りと書き込み	gws.sheets.*
   documents	Google Docs のコンテンツの読み取りと書き込み	gws.docs.*
   contacts.readonly	自分の Google Contacts の読み取り専用検索	gws.contacts.search
   directory.readonly	Workspace 組織ディレクトリの読み取り専用検索（Workspace アカウントのみ）	gws.contacts.directory_search
   tasks	Google Tasks のリストとタスクの読み取りと書き込み	gws.tasks.*
   presentations	Google Slides のコンテンツの読み取りと書き込み	gws.slides.*
   userinfo.email	承認したアカウントを識別（再認証時のメールアドレス照合）	アカウント管理
   userinfo.profile	メールアドレスとともに表示名を保存	アカウント管理

5. テストユーザーを追加 — 対象ユーザー に移動します：

   • 接続する予定の Google メールアドレスをそれぞれ追加します。
   • ⚠️ これは必須です — 追加しないと、OAuth 中に「アクセスがブロックされました。このアプリは Google の確認手続きを完了していません」（エラー 403）が表示されます。

6. OAuth 認証情報を作成 — クライアント に移動します：

   • 「+ クライアントを作成」→「OAuth クライアント ID」をクリックします。
   • アプリケーションの種類：デスクトップアプリ
   • 「作成」をクリックします。
   • JSON ファイルをダウンロードします（ダウンロードアイコンをクリック）— このファイルにはクライアント ID とクライアントシークレットが含まれています。

複数の組織

異なる Google Workspace 組織のアカウントを接続する場合は、組織ごとに GCP プロジェクトが必要です。各プロジェクトで OAuth 認証情報を作成し、接続時に指定してください：

gws.accounts.add(label: "work", clientId: "work-client-id", clientSecret: "work-secret")
gws.accounts.add(label: "personal", clientId: "personal-client-id", clientSecret: "personal-secret")

クライアントシークレットは OS のキーチェーンに保存されます。クライアント ID はアカウントレジストリに保存されます。

アーキテクチャ

gws-connector/
├── cmd/gws-mcp/                 # MCP server entrypoint
├── internal/
│   ├── accounts/                # Account registry & router
│   ├── auth/                    # OAuth flow, token store, client factory
│   ├── server/                  # MCP tool registration & dispatch
│   └── services/                # Gmail, Calendar, Drive API wrappers
│
├── .claude-plugin/              # Claude Code plugin manifest + marketplace
├── .mcp.json                    # Claude Code MCP config
├── gemini-extension.json        # Gemini CLI extension manifest
├── CONTEXT.md                   # Shared behavioral context (both agents)
├── skills/                      # Slash commands (Claude Code + Gemini CLI)
├── hooks/                       # Claude Code session hooks
├── agents/                      # Claude Code workspace agent
│
├── .vscode/mcp.json             # GitHub Copilot MCP config
├── .cursor/mcp.json             # Cursor MCP config
└── codex.json                   # OpenAI Codex CLI config

• トークンの保存：OS のキーチェーン（macOS Keychain、GNOME Keyring、Windows Credential Manager）を使用し、自動的にファイルへフォールバックします
• クライアントシークレット：アカウントごとに OS のキーチェーンに保存します（設定ファイルには保存されません）
• アカウントレジストリ：~/.claude/channels/gws/accounts.json にある JSON ファイルです（クライアント ID とメタデータを含み、シークレットは含みません）
• 認証情報の解決：アカウントごとの認証情報（キーチェーン）→ グローバル環境変数へのフォールバック
• プロトコル：stdio 経由の MCP（Model Context Protocol） — あらゆる MCP クライアントに対応しています

開発

make build          # Build binary
make test           # Run tests with race detector
make test-verbose   # Run tests with verbose output
make lint           # Run go vet
make release        # Cross-compile for all platforms
make clean          # Remove build artifacts

ライセンス

MIT — LICENSE を参照してください。