better-workspace-mcp

workspace

Google Workspace MCP — Docs、Drive、Calendar、Gmail、Sheets、Slides、Tasks、Chat、People、Forms

2026-09-13 にアーカイブ — このリポジトリはメンテナンスされていません。この MCP サーバーの代わりに、Google Workspace の公式 API をご利用ください。既存のインストールは引き続き動作しますが、更新やサポートは提供されません。

ドキュメント · インストール · クイックスタート · コミュニティ

n24q02m の関連プロジェクト（クリックして展開）

| プロジェクト | キャッチコピー | タグ | |---|---|---| | [agent-chat-plugin](https://github.com/n24q02m/agent-chat-plugin) | AI エージェント同士が共有フォルダーでチャットします。人間による中継もオーケストレーターも不要です。... | ツール | | [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) | トークン効率に優れたコードレビューのためのナレッジグラフ。セマンティック検索と呼び出し... | MCP | | [better-drive](https://github.com/n24q02m/better-drive) | .driveignore フィルターを備えた双方向の Google Drive 同期。rclone エンジン、Windows トレイ | ツール | | [better-email-mcp](https://github.com/n24q02m/better-email-mcp) | AI エージェント向け IMAP/SMTP メール機能。読み取り、送信、フォルダー整理、属性管理... | MCP | | [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) | Godot Engine 用の複合 MCP サーバー。AI 支援のゲーム制作向けに17個の複合ツールを提供... | MCP | | [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp) | AI エージェント向けの Markdown ファーストな Notion。ページ、データベース、ブロック、コメント... | MCP | | [better-semantic-release](https://github.com/n24q02m/better-semantic-release) | リリース安全性ガードを内蔵した、すぐに置き換え可能な python-semantic-release フォーク（孤立... | ツール | | [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) | AI エージェント向け Telegram。両方のボ...にわたるメッセージ、チャット、メディア、連絡先 | MCP | | [better-workspace-mcp](https://github.com/n24q02m/better-workspace-mcp) | Google Workspace MCP サーバー（Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch...） | MCP | | [claude-plugins](https://github.com/n24q02m/claude-plugins) | n24q02m の MCP サーバー向け Claude Code プラグインマーケットプレイス。ウェブ検索をインストール... | マーケットプレイス | | [imagine-mcp](https://github.com/n24q02m/imagine-mcp) | AI エージェント向けの画像・動画の理解と生成。Gemini、Open...に対応 | MCP | | [jules-task-archiver](https://github.com/n24q02m/jules-task-archiver) | batchexecute API を使用して Jules タスクを一括操作する Chrome 拡張機能。... | ツール | | [mcp-core](https://github.com/n24q02m/mcp-core) | MCP サーバー構築のための共通基盤。Streamable HTTP トランスポート、OAuth... | MCP | | [mnemo-mcp](https://github.com/n24q02m/mnemo-mcp) | ハイブリッド検索と埋め込み同期を備えた永続的な AI メモリ。オープン、無料、無制限... | MCP | | [qwen3-embed](https://github.com/n24q02m/qwen3-embed) | ONNX Runtime と GGUF による軽量な Qwen3 テキスト埋め込みと再ランキング | ライブラリ | | [skret](https://github.com/n24q02m/skret) | サーバー不要のシークレット管理。 | CLI | | [tacet](https://github.com/n24q02m/tacet) | ナレッジ全体に LLM コストを償却する、自己蒸留型のニューロシンボリック・カスケード... | ツール | | [web-core](https://github.com/n24q02m/web-core) | 検索、スクレイピング、HTTP セキュリティ、スト...のための共通ウェブ基盤パッケージ | ライブラリ | | [wet-mcp](https://github.com/n24q02m/wet-mcp) | AI エージェント向けオープンソース MCP サーバー。ウェブ検索、コンテンツ抽出、ライブラリ... | MCP |

目次

• インストール
• リモート（HTTP モード）
• ツール
• クイックスタート
• 複数アカウント
• ドキュメント
• デプロイ
• 引き継ぎ
• コントリビューション
• ライセンス

インストール

サーバーは stdio（デフォルト、シングルユーザー、ご自身の Google OAuth クライアントを 1 つ使用）と HTTP（マルチユーザー、ユーザーごとのベアラートークン）の 2 つのモードで動作します。stdio の場合は、MCP クライアントの設定に追加してください。

{
  "mcpServers": {
    "workspace": {
      "command": "npx",
      "args": ["--yes", "@n24q02m/workspace@latest"],
      "env": {
        "GOOGLE_OAUTH_CLIENT_ID": "<your-client-id>.apps.googleusercontent.com",
        "GOOGLE_OAUTH_CLIENT_SECRET": "<your-client-secret>"
      }
    }
  }
}

パッケージは @n24q02m/workspace です（以前の名前は @n24q02m/better-workspace-mcp。旧パッケージは最後のリリースを 1 回行った後、更新を終了します）。MCP Registry の ID は io.github.n24q02m/better-workspace-mcp のままで、従来の better-workspace-mcp コマンドは workspace のエイリアスとして引き続き使用できます。

これら 2 つの値は、Google Cloud Console の「API とサービス」→「認証情報」で作成する デスクトップアプリ タイプの OAuth 2.0 クライアントから取得します。サーバーは公開 URL ではなく、ループバックアドレスで同意画面からのリダイレクトを受信するため、デスクトップが適切なタイプです。同じプロジェクトで、呼び出す予定の Workspace API を有効にし、同意画面を公開していない間に、ご自身をテストユーザーとして追加してください。

初回起動時は、ブラウザーで Google の同意画面が開きます。リフレッシュトークンは、お使いのマシンの ~/.better-workspace/ に暗号化して保存されます（従来の ~/.better-workspace-mcp/ があれば、フォールバックとして読み込まれます）。そのため、以降の起動時には再度確認を求められません。

同じサーバーを HTTP 経由で複数のユーザーに提供することもできます。詳しくはリモート（HTTP モード）をご覧ください。

AI エージェントでインストール -- これを AI コーディングエージェントに貼り付けてください。

次の手順に従って MCP サーバー workspace をインストールしてください。 https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-workspace-mcp/setup-with-agent.md

リモート（HTTP モード）

stdio に加えて、サーバーはマルチユーザー HTTP サービスとして動作します。各リクエストには、ユーザーファイル（WORKSPACE_USERS_FILE）のベアラートークンが含まれます。各ユーザーの Google 認証情報は、そのユーザーの名前空間をキーとする個別のバケットに保存されるため、1 つのデプロイで、アカウントを共有することなく複数のユーザーにサービスを提供できます。HTTP アカウントの Google 認証はホスト上で行われ、workspace auth --user <namespace> を使用します。

デプロイしたホストを MCP クライアントの接続先に指定してください。

{
  "mcpServers": {
    "workspace": {
      "type": "http",
      "url": "https://<your-host>/mcp"
    }
  }
}

モード

モードは 2 つだけです。プロキシモードやデーモンモードはありません。stdio は MCP の stdio トランスポートを直接使用し、その内部で HTTP を介しません。

モード	選択方法	対象	Google OAuth クライアント
stdio	デフォルト	ユーザー 1 人、自身のマシン上	デスクトップアプリ
http	--http、MCP_TRANSPORT=http、または TRANSPORT_MODE=http	複数のユーザー、ユーザー名前空間ごとに個別の認証情報バケット	ウェブアプリケーション

OAuth クライアントは 1 つではなく 2 つ

Google は OAuth クライアントの 種類 にリダイレクト URI を紐づけるため、2 つのモードで同じクライアントを共有することはできません。stdio では、任意のループバックポートにリダイレクトできる デスクトップ クライアントを使用します。HTTP では ウェブ クライアントを使用します。2 つの認証情報は別々の名前で管理してください。stdio も実行するマシンで GOOGLE_OAUTH_CLIENT_ID／_SECRET にウェブクライアントを設定すると、stdio のインストールはすべて動作しなくなります。そのため、docker-compose.http.yml はウェブ用のペアを GOOGLE_OAUTH_WEB_CLIENT_ID／_SECRET として読み込み、コンテナーに渡す際に名前を変更します。

環境

変数	必須	説明
GOOGLE_OAUTH_CLIENT_ID	はい	Web クライアント ID です。これがないとサーバーは起動しません。
GOOGLE_OAUTH_CLIENT_SECRET	はい	Web クライアントシークレットです。同様に必須です。
CREDENTIAL_SECRET	はい	各ユーザーの認証情報ストアの暗号化キーを導出します。ユーザーの同意の途中で失敗するのではなく、これがないとサーバーは起動しません。
WORKSPACE_USERS_FILE	HTTP では必須	各ベアラートークンをユーザーネームスペースに対応付けるユーザーファイルです（hull の multi 認証）。未設定の場合は hull のデフォルトの場所を使用します。
PORT	いいえ	リッスンポートです。0（デフォルト）を指定すると、OS が空いているポートを割り当てます。
HOST	いいえ	バインドアドレスです。デフォルトはループバックアドレスのため、コンテナーでは 0.0.0.0 が必要です。

認証情報は、コンテナー内のデータボリュームである ~/.better-workspace/ の下にローカル保存されます。以前の ~/.better-workspace-mcp/ はフォールバックとして読み込まれます。

このリポジトリの docker-compose.http.yml は、これらの変数を記述した実行可能なオーバーレイです。

ツール

Workspace の各ドメインに 1 つの複合ツールがあり、config と help も用意されています。

ツール	対象
docs	Google Docs -- getText、create、writeText、getSuggestions、replaceText、formatText
drive	ファイルとフォルダー -- search、findFolder、createFolder、moveFile、renameFile、trashFile、downloadFile、getComments
calendar	イベント -- listCalendars、listEvents、getEvent、createEvent、updateEvent、deleteEvent、respondToEvent、findFreeTime
gmail	メール -- search、get、send、createDraft、sendDraft、modify、batchModify、modifyThread、downloadAttachment、listLabels、createLabel
sheets	スプレッドシート、読み取り専用 -- getText、getRange、getMetadata
slides	プレゼンテーション -- スライド、テキスト、図形、画像、表、発表者ノートを扱う 19 個のアクション
tasks	タスクリストとタスク -- listTaskLists、listTasks、createTask、updateTask、completeTask、deleteTask
chat	Google Chat -- listSpaces、findSpaceByName、setUpSpace、getMessages、listThreads、sendMessage、sendDm、findDmByEmail
people	プロフィールの検索 -- getMe、getUserProfile、getUserRelations
forms	フォーム -- create、get、batchUpdate、listResponses、getResponse
time	ローカルの日付／時刻／タイムゾーンのヘルパー（Google アカウントは不要）
config	認証情報の状態とアカウント管理
help	任意のツールの完全なドキュメント

フォームへの質問の追加には create ではなく、forms(action="batchUpdate") を使用します。Forms API では回答を書き込めないため、回答は読み取り専用です。フォームの一覧表示や削除には drive を使用します。

クイックスタート

config ツールで認証情報が反映されたことを確認します。最初の同意を行う前は awaiting_setup が表示され、その後はサーバーが操作しているアカウント名が表示されます。

{ "action": "status" }

次に、ドメインツールを呼び出します。docs の create は新しいドキュメントの ID を返し、getText で内容を読み取れます。

{ "action": "create", "title": "Notes", "content": "First line." }
{ "action": "getText", "documentId": "<id-from-create>" }

time、config、help は Google アカウントが不要なため、同意前でも応答します。time を呼び出すと、サーバーが正しく接続されているかを最も手早く確認できます。

{ "action": "getCurrentTime" }

2 つ目の Google アカウントとして操作する方法については、複数アカウントを参照してください。

複数アカウント

すべてのドメインツールは account パラメーター（呼び出しの対象となる Google アカウントのメールアドレス）を受け取ります。省略すると、呼び出しはプライマリアカウントに対して実行されます。

{ "action": "search", "query": "is:unread", "account": "[email protected]" }
{ "action": "search", "query": "is:unread" }

この 2 つの gmail 呼び出しは、異なる 2 つのメールボックスを読み取ります。1 つ目は [email protected]、2 つ目はプライマリアカウントです。

アカウントは config ツールで管理します。

呼び出し	結果
config(action="account_add")	stdio では、開くための URL が返されます。そこで Google の同意を完了すると、アカウントが 1 つ追加されます。HTTP では、ホスト上で実行する workspace auth --user <namespace> コマンドが返されます。
config(action="account_list")	設定済みのアカウントと、どれがプライマリアカウントかを表示します。
config(action="account_remove", account="<email>")	アカウントを 1 つ削除します。
config(action="account_set_default", account="<email>")	アカウントを 1 つプライマリアカウントに設定します。

最初に認可されたアカウントがプライマリアカウントになります。プライマリアカウントを削除すると、残りのアカウントの 1 つが昇格します。最後のアカウントを削除すると、サーバーはセットアップ待ちの状態に戻ります。設定されていないアカウントを指定すると、そのアカウント名を示すエラーが発生します。黙ってプライマリアカウントにフォールバックすると、誤ったメールボックスを操作することになるため、呼び出し先が変更されることはありません。

account_add はトランスポートに応じてフローを選択します。stdio では一時的なループバック同意サーバーを起動し、URL を返します。HTTP では同意画面を提供せず、ホストで実行する workspace auth --user <namespace> コマンドを返します。

value="primary" は stdio 専用です。リモートの呼び出し元は account_set_default でデフォルトを変更します。

以前の単一アカウント版からの移行

マルチアカウント対応より前のビルドで保存された認証情報は、トークンをまとめた 1 つのデータです。その後の初回実行時に、そのデータはアカウントのメールアドレスを使ってマルチアカウント形式に移行されます。メールアドレスは、保存された id_token があればそこから取得されます。ネットワークは不要で、通常はこちらの方法が使われます。そうでない場合、サーバーは Google の userinfo エンドポイントに問い合わせます。そのためにはネットワークアクセスと、有効期限が切れていないか更新可能なトークンが必要です。

どちらの方法でも取得できない場合、保存されたトークンがまだ有効でも、サーバーはセットアップ待ちの状態であることを報告し、ブラウザーで OAuth フローを開始します。同意を完了すれば問題なく動作し、何も破棄されません。認可したばかりのアカウントが保存されてプライマリアカウントになり、古いトークンは上書きされずに (unidentified) というキーの下に引き継がれます。その後、config(action="account_list") を実行すると、次の 2 つのエントリーが表示されます。

{ "accounts": ["(unidentified)", "[email protected]"], "primary": "[email protected]" }

実際のアカウントが残っている間、(unidentified) がプライマリアカウントに昇格することはなく、明示的に指定しない限り、どの呼び出しもそこにはルーティングされません。所有者を特定できなかった認証情報が黙って破棄されないように保持されています。再認可したアカウントが動作することを確認したら、削除してください。

{ "action": "account_remove", "account": "(unidentified)" }

移行が正常に完了すると（通常はこちらに該当します）、config(action="account_list") にはアカウントが 1 つだけ表示され、それがプライマリアカウントになります。

Forms のスコープと再同意

同意画面では forms ツールが追加される前から Google Forms のスコープを要求していたため、追加の同意手続きなしで利用できます。

これらのスコープが追加される前に認可されたアカウントも対象ですが、別の方法で対応します。このサーバーが呼び出すすべての Forms メソッドでは、Forms スコープの代わりに https://www.googleapis.com/auth/drive を Google が受け入れます。また、完全な drive スコープは最初のリリースから同意画面に含まれています。Google は発行済みのトークンのスコープを拡張しないため、いずれのスコープも含まれていない場合（同意画面でユーザーが個別の制限付きスコープを拒否することがあります）、最初の forms 呼び出しは 403（Request had insufficient authentication scopes）を返します。そのアカウントだけを config(action="account_add") で再認可し、同じアカウントでログインしてください。レコードはその場で置き換えられるため、ほかに変更はありません。

ドキュメント

ドキュメント全文は mcp.n24q02m.com/servers/better-workspace-mcp/ をご覧ください。

• セットアップ -- プラグインのインストール、Docker の stdio、Docker の HTTP メソッド
• モードの概要 -- stdio（デフォルト）と HTTP（複数ユーザー、ベアラートークン）
• 複数ユーザーのセットアップ -- リモート（HTTP モード）を支える、名前空間ごとの認証情報モデル

各ツールは実行時に自身についても説明します。help を呼び出すと、各アクションの正確なパラメーターを含む完全なリファレンスを確認できます。

デプロイ

このサーバーでは、ホスト型エンドポイントを運用していません。サポート対象は、上記の stdio インストールと、独自の HTTP デプロイをセルフホストする方法です。

HTTP モードをセルフホストするには、このリポジトリの compose オーバーレイを実行します。

docker compose -f docker-compose.yml -f docker-compose.http.yml up

ローカルで http イメージをビルドし、ホストのループバックインターフェースのみで公開します。GOOGLE_OAUTH_WEB_CLIENT_ID、GOOGLE_OAUTH_WEB_CLIENT_SECRET、CREDENTIAL_SECRET、WORKSPACE_USERS_FILE は、シェルまたは .env ファイルで設定します（環境変数を参照）。ユーザーファイルでは、各ベアラートークンをユーザー名前空間に対応付けます。アカウントはホスト上で workspace auth --user <namespace> を使って追加します。ローカルマシン以外から利用する場合は、そのホスト上で手前に独自の TLS リバースプロキシを配置してください。

各リリースでは、Docker Hub と GHCR にマルチアーキテクチャ対応のコンテナイメージも公開しています。デフォルトのステージは http サーバーです。

貢献

CONTRIBUTING.md をご覧ください。

ライセンス

Apache-2.0 © n24q02m