Google Workspace MCP Server

Google Workspace MCP サーバー

モデル コンテキスト プロトコルを介して、MCP クライアント、AI アシスタントなどを Google Workspace サービスに接続します。

実際に動作しているところをご覧ください:

📑 目次

• 概要
• 特徴
• クイックスタート
  • 前提条件
  • インストール
  • 構成
  • サーバーを起動する
  • サーバーへの接続
  • Open WebUIとの統合
  • 初回認証
• 利用可能なツール
  • カレンダー
  • Googleドライブ
  • Gメール
  • Googleドキュメント
• 発達
  • プロジェクト構造
  • OAuth のポート処理
  • デバッグ
  • 新しいツールの追加
• セキュリティノート
• ライセンス

🌐 概要

Google Workspace MCP サーバーは、モデルコンテキスト プロトコル（MCP）を使用して、Google Workspace サービス（カレンダー、ドライブ、Gmail、ドキュメント）を AI アシスタントやその他のアプリケーションと統合します。これにより、AI システムは Google Workspace アプリケーションからユーザーデータに安全かつ効率的にアクセスし、操作できるようになります。

✨ 特徴

• 🔐 OAuth 2.0 認証: 自動トークン更新と集中認証フローにより、ユーザーが承認した認証情報を使用して Google API に安全に接続します。
• 📅 Google カレンダーの統合: 完全なカレンダー管理 - カレンダーの一覧表示、イベントの取得、終日イベントと時間指定イベントのサポートによるイベントの作成/変更/削除
• 📁 Google Drive との連携：ファイルの検索、フォルダ内容の一覧表示、ファイル内容の読み取り、新規ファイルの作成が可能です。.docx、.xlsx、その他の Microsoft Office 形式のファイルの抽出と取得をネイティブにサポートしています。
• 📧 Gmail 統合: 完全なメール管理 - メッセージの検索、コンテンツの取得、メールの送信、すべてのクエリ構文を完全にサポートした下書きの作成
• 📄 Google ドキュメントの統合: チャットから直接、ドキュメントを検索したり、ドキュメントの内容を読み取ったり、フォルダー内のドキュメントを一覧表示したり、新しいドキュメントを作成したりできます。
• 🔄 複数のトランスポート オプション: ストリーミング可能な HTTP + SSE フォールバック
• 🔌 mcpo互換性: Open WebUI などのツールとの統合のために、サーバーを OpenAPI エンドポイントとして簡単に公開できます。
• 🧩 拡張可能な設計: より多くの Google Workspace API とツールのサポートを追加するためのシンプルな構造
• 🔄統合されたOAuthコールバック：ポート8000でサーバー内で直接OAuthリダイレクトを処理します
• ⚡ スレッドセーフなセッション管理: 信頼性を向上させるスレッドセーフなアーキテクチャによる堅牢なセッション処理

🚀 クイックスタート

前提条件

• Python 3.11以上
• **uv**パッケージインストーラー（または pip）
• 必要な API（カレンダー、ドライブ、Gmail、ドキュメント）に対して OAuth 2.0 認証情報が有効になっているGoogle Cloud プロジェクト

インストール

構成

1. Google Cloud ConsoleでOAuth 2.0 認証情報（デスクトップ アプリケーション タイプ）を作成します。
2. プロジェクトでGoogle カレンダー API 、 Google ドライブ API 、 Gmail API 、 Google ドキュメント API を有効にします。
3. OAuth クライアント資格情報をclient_secret.jsonとしてダウンロードし、プロジェクトのルート ディレクトリに配置します。
4. Google Cloud Console の OAuth クライアント設定に、以下のリダイレクト URI を追加してください。デフォルトのベース URI とポートはhttp://localhost:8000です。これらは環境変数（ WORKSPACE_MCP_BASE_URIとWORKSPACE_MCP_PORT ）でカスタマイズできます。これらの値を変更した場合は、Google Cloud Console のリダイレクト URI もそれに応じて更新する必要があります。
   http://localhost:8000/oauth2callback
5. ⚠️ 重要: client_secret.jsonが.gitignoreファイルに追加され、バージョン管理にコミットされていないことを確認してください。

サーバー構成

サーバーのベース URL とポートは、環境変数を使用してカスタマイズできます。

• WORKSPACE_MCP_BASE_URI : サーバーのベースURIを設定します（デフォルト: http://localhost ）。これは、Geminiネイティブ関数の呼び出しに使用されるserver_urlとOAUTH_REDIRECT_URIに影響します。
• WORKSPACE_MCP_PORT : サーバーがリッスンするポートを設定します（デフォルト： 8000 ）。これはserver_url 、 port 、およびOAUTH_REDIRECT_URIに影響します。

使用例:

環境設定

開発中、サーバーはローカルホストのOAuthコールバックにHTTPを使用します。サーバーを実行する前に、以下の環境変数を設定してください。

これを行わないと、認証フロー中に「OAuth 2 は HTTPS を使用する必要があります」というエラーが発生する可能性があります。

サーバーを起動する

サーバーを実行するには、次のいずれかの方法を選択します。

ポート 8000 で HTTP トランスポート層を使用してサーバーを実行します。

マルチユーザーMCPは少々扱いにくいため、現状ではクライアントとサーバーを1:1でマッピングすることで最も効率的に動作します。ClaudeがOAuth 2.1フローを実行できるようになれば状況は変わります。そのため、このMCPは簡素化されたシングルユーザー環境向けのフラグを使用して構築されています。サーバーをシングルユーザーモードで実行すると、セッションとOAuthのマッピングがバイパスされ、 .credentialsディレクトリにある利用可能な認証情報が使用されます。

シングルユーザーモードの場合:

• サーバーは、 .credentialsディレクトリ内の有効な資格情報を自動的に検索して使用します。
• セッションマッピングは必要ありません。サーバーは最初に見つかった有効な認証情報ファイルを使用します。
• 開発、テスト、または単一ユーザーの展開に役立ちます
• 認証情報ファイルを作成するには、依然として初期OAuth認証が必要です

このモードは、マルチユーザー セッション管理を必要とせず、資格情報の処理を簡素化したい場合に特に役立ちます。

提供されているDockerfileを使用してサーバーを構築および実行できます。

smithery.yamlファイルは、Docker コンテナ内でサーバーを正しく起動するように構成されています。

重要な港

デフォルトのポートは8000ですが、 WORKSPACE_MCP_PORT環境変数を使用して変更できます。

サーバーへの接続

サーバーは複数の接続方法をサポートしています:

クロードデスクトップ:

どこでも実行でき、 mcp-remote経由で使用することも、引数としてuv run main.pyを使用するか、localhost でmcp-remoteを使用してローカルで呼び出すこともできます。

config.json:

1. mcpoをインストールします: uv pip install mcpoまたはpip install mcpo
2. config.jsonを作成します（ Open WebUI との統合を参照）
3. 設定を指定してmcpoを実行します: uvx mcpo --config config.json --port 8001
4. MCP サーバー API は次の場所で利用できます: http://localhost:8001/google_workspace (またはconfig.jsonで定義された名前)
5. OpenAPI ドキュメント (Swagger UI) は次の場所から入手できます: http://localhost:8001/google_workspace/docs

起動コマンドを使用する場合 (単一 mcp mcpo の使用の場合):

1. mcpoをインストールします: uv pip install mcpoまたはpip install mcpo
2. uvx mcpo --port 8001 --api-key "top-secret" --server-type "streamablehttp" -- http://localhost:8000/mcpで開始します。
3. MCP サーバー API は次の場所で利用できます: http://localhost:8001/openapi.json (またはconfig.jsonで定義された名前)
4. OpenAPI ドキュメント (Swagger UI) は次の場所から入手できます: http://localhost:8001/docs
5. HTTPモードでサーバーを起動します（サーバーの起動を参照）
6. MCP JSONリクエストをhttp://localhost:8000に直接送信します。
7. curlやカスタムHTTPクライアントなどのツールを使ったテストに便利
8. Claude Desktop やその他の MCP クライアントにサービスを提供するために使用できますが、mcp-remote 経由で新しいストリーミング可能な HTTP トランスポートを統合する必要があります。
9. 必要に応じて、SSE フォールバック モードで提供することもできます。

Open WebUIとの統合

このサーバーを Open WebUI 内のツールプロバイダーとして使用するには:

1. mcpo構成の作成: 次の構造を持つconfig.jsonという名前のファイルを作成し、mcpo がストリーミング可能な HTTP エンドポイントを OpenAPI 仕様ツールとして使用できるようにします。
   { "mcpServers": { "google_workspace": { "type": "streamablehttp", "url": "http://localhost:8000/mcp" } } }
2. mcpoサーバーを起動します。
   mcpo --port 8001 --config config.json --api-key "your-optional-secret-key"
   このコマンドはmcpoプロキシを起動し、アクティブな（ポート 8000 と想定）Google Workspace MCP をポート 8001 で提供します。
3. Open WebUI を設定します:
   • Open WebUIの設定に移動します
   • 「接続」→「ツール」へ移動します
   • 「ツールを追加」をクリック
   • サーバー URL を入力します: http://localhost:8001/google_workspace ( config.jsonのmcpoベース URL とサーバー名に一致)
   • mcpoで--api-keyを使用した場合は、それを API キーとして入力します。
   • 設定を保存する
   • Open WebUI でモデルを操作するときに、Google Workspace ツールが利用できるようになります。

初回認証

Google API アクセスを必要とするツールが呼び出されると、次のようになります。

• ツールにuser_google_emailが指定されており、認証情報が欠落または無効の場合：サーバーは自動的にOAuth 2.0フローを開始します。認証URLはMCPレスポンスで返されます（またはコンソールに表示されます）。
• user_google_emailが指定されておらず、認証情報が欠落または無効の場合：ツールはエラーメッセージを返します。LLMは、集中管理されたstart_google_authツールを使用するように指示されますstart_google_authは、ユーザーのメールアドレスと適切なservice_name （例："Google Calendar", "Google Docs", "Gmail", "Google Drive"）を指定して start_google_auth を呼び出します。これにより、認証URLも返されます。

ユーザーの手順 (認証 URL を取得した後):

1. 提供された承認 URL を Web ブラウザーで開きます。
2. Google アカウントにログインし、指定されたサービスに対して要求された権限を付与します。
3. 承認後、Google はブラウザをhttp://localhost:8000/oauth2callback (または設定されたリダイレクト URI) にリダイレクトします。
4. MCP サーバーはこのコールバックを処理し、認証コードをトークンと交換し、資格情報を安全に保存します。
5. LLM は元のリクエストを再試行できます。同じユーザーとサービスに対する以降の呼び出しは、リフレッシュトークンが期限切れになるか取り消されるまで、再認証なしで動作するはずです。

🧰 利用可能なツール

注: 特定のGoogleサービス用のツールを初めて使用する場合、有効な認証情報がまだ保存されておらず、ツールにuser_google_emailが指定されていると、OAuth認証フローがトリガーされることがあります。認証が必要で、ツールにuser_google_email指定されていない場合、LLMはユーザーのメールアドレスと適切なservice_nameを指定して、集中管理されたstart_google_authツール（ core/server.pyで定義）を使用する必要があります。

📅 Googleカレンダー

ソース: gcalendar/calendar_tools.py

ℹ️ すべてのカレンダーツールは、現在のMCPセッション（ mcp_session_id ）経由の認証、またはuser_google_emailへのフォールバックをサポートしています。どちらも利用できず認証が必要な場合は、ツールはエラーを返し、LLMにユーザーのメールアドレスとservice_name="Google Calendar"を指定して集中管理されたstart_google_authツールを使用するよう促します。

🕒 日付/時刻パラメータ: ツールは、RFC3339に準拠した完全なタイムスタンプ（例：2024-05-12T10:00:00Z）と単純な日付（例：2024-05-12）の両方に対応しています。サーバーは必要に応じて自動的にフォーマットします。

📁 Googleドライブ

ソース: gdrive/drive_tools.py

クエリ構文: Google ドライブの検索クエリについては、ドライブの検索クエリ構文を参照してください。

📧 Gメール

ソース: gmail/gmail_tools.py

クエリ構文: Gmail の検索クエリについては、 Gmail の検索クエリ構文を参照してください。

📝 Google ドキュメント

出典: gdocs/docs_tools.py

🛠️ 開発

プロジェクト構造

OAuth のポート処理

サーバーは、別の Web サーバー フレームワークを必要とせずに、OAuth 2.0 リダイレクト URI ( /oauth2callback ) を巧みに処理します。

• HTTPモードまたはmcpo経由で実行する場合、基盤となるMCPライブラリの組み込みHTTPサーバー機能を利用します。
• ポート8000の/oauth2callback専用のカスタムMCPルートが登録されています。
• Googleが認証後にユーザーをリダイレクトすると、MCPサーバーはこのルートでリクエストを傍受します。
• authモジュールは認証コードを抽出し、トークン交換を完了します。
• コールバックはhttp://localhost使用するため、ローカルで実行する場合はOAUTHLIB_INSECURE_TRANSPORT=1を設定する必要があります。

デバッグ

認証手順やAPI呼び出しを含む詳細なログについては、 mcp_server_debug.logを確認してください。必要に応じてデバッグログを有効にしてください。

• client_secret.jsonが正しく存在することを確認する
• Google Cloud Console で正しいリダイレクト URI ( http://localhost:8000/oauth2callback ) が設定されていることを確認します。
• Google Cloud プロジェクトで必要な API（カレンダー、ドライブ、Gmail）が有効になっていることを確認します
• サーバープロセスが実行される環境でOAUTHLIB_INSECURE_TRANSPORT=1設定されていることを確認します。
• ブラウザベースのOAuthフロー中に特定のエラーメッセージを探す

Google API から返されたトレースバックまたはエラー メッセージがないか、サーバー ログを確認します。

新しいツールの追加

1. 適切なモジュールを選択または作成します（例： gdocs/gdocs_tools.py ）
2. 必要なライブラリ（Google API クライアント ライブラリなど）をインポートします。
3. ツールロジック用のasync関数を定義します。パラメータには型ヒントを使用します。
4. 関数を@server.tool("your_tool_name")で装飾します。
5. 関数内で、認証された資格情報を取得します。

6. Google API サービス クライアントをビルドします: service = build('drive', 'v3', credentials=credentials)
7. Google APIを呼び出すロジックを実装する
8. 潜在的なエラーを適切に処理する
9. 結果をJSONシリアル化可能な辞書またはリストとして返します
10. main.pyにツール関数をインポートして、サーバーに登録します。
11. ツールのモジュールで必要なサービス固有のスコープ定数を定義します
12. 新しい依存関係が必要な場合はpyproject.tomlを更新します

スコープ管理： config/google_config.pyのグローバルSCOPESリストは、OAuth 同意画面の初期表示に使用されます。各ツールは、 get_credentialsを呼び出す際に、必要最小限のrequired_scopesをリクエストする必要があります。

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

• client_secret.json : このファイルには機密性の高い認証情報が含まれています。バージョン管理にコミットしないでください。.gitignore .gitignoreに記載されていることを確認してください。安全に保管してください。
• ユーザートークン：認証されたユーザーの認証情報（リフレッシュトークン）はcredentials-<user_id_hash>.jsonなどのファイルにローカルに保存されます。これらのファイルはユーザーのGoogleアカウントデータへのアクセスを許可するため、保護する必要があります。また、 .gitignoreにも保存されていることを確認してください。
• OAuth コールバックのセキュリティ：OAuth コールバックにhttp://localhostを使用するのは、開発中のインストール済みアプリケーションでは標準ですが、 OAUTHLIB_INSECURE_TRANSPORT=1必要です。localhost 以外の本番環境デプロイメントでは、コールバック URI に HTTPS を使用し、Google Cloud Console で適切に設定する必要があります。
• mcpoセキュリティ: mcpoを使用してネットワーク経由でサーバーを公開する場合は、次の点を考慮してください。
  • 基本認証に--api-keyオプションを使用する
  • HTTPS の終了、適切なログ記録、より堅牢な認証を処理するために、リバース プロキシ (Nginx や Caddy など) の背後でmcpoを実行します。
  • ローカルホストを超えて公開する場合は、信頼できるネットワークインターフェースにのみmcpoをバインドします。
• スコープ管理：サーバーは、カレンダー、ドライブ、Gmail に対して特定の OAuth スコープ（権限）を要求します。ユーザーは初期認証時にこれらのスコープに基づいてアクセスを許可します。実装されたツールに必要な範囲を超えるスコープを要求しないでください。

スクリーンショット:

📄 ライセンス

このプロジェクトは MIT ライセンスに基づいてライセンスされています - 詳細についてはLICENSEファイルを参照してください。