Google Workspace MCP サーバー

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

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

📑 目次

• 概要

• 特徴

• クイックスタート

  • 前提条件

  • インストール

  • 構成

  • サーバーを起動する

  • サーバーへの接続

  • Open WebUIとの統合

  • 初回認証

• 利用可能なツール

  • カレンダー

  • Googleドライブ

  • Gメール

  • Googleドキュメント

• 発達

  • プロジェクト構造

  • OAuth のポート処理

  • デバッグ

  • 新しいツールの追加

• セキュリティノート

• ライセンス

Related MCP server: Google Workspace MCP Server

🌐 概要

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 プロジェクト

インストール

# Clone the repository (replace with your fork URL if different)
git clone https://github.com/taylorwilsdon/google_workspace_mcp.git
cd google_workspace_mcp

# Create a virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`
uv pip install -e .

構成

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に影響します。

使用例:

export WORKSPACE_MCP_BASE_URI="https://my-custom-domain.com"
export WORKSPACE_MCP_PORT="9000"
uv run main.py

環境設定

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

# Allow HTTP for localhost OAuth callbacks (development only!)
export OAUTHLIB_INSECURE_TRANSPORT=1

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

サーバーを起動する

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

python main.py
# or using uv
uv run main.py

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

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

python main.py --single-user
# or using uv
uv run main.py --single-user

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

• サーバーは、 .credentialsディレクトリ内の有効な資格情報を自動的に検索して使用します。

• セッションマッピングは必要ありません。サーバーは最初に見つかった有効な認証情報ファイルを使用します。

• 開発、テスト、または単一ユーザーの展開に役立ちます

• 認証情報ファイルを作成するには、依然として初期OAuth認証が必要です

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

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

# Build the Docker image
docker build -t google-workspace-mcp .

# Run the Docker container
# The -p flag maps the container port 8000 to the host port 8000
# The -v flag mounts the current directory to /app inside the container
# This is useful for development to pick up code changes without rebuilding
docker run -p 8000:8000 -v $(pwd):/app google-workspace-mcp

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

重要な港

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

サーバーへの接続

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

クロードデスクトップ:

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

config.json:

{
  "mcpServers": {
    "Google workspace": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8000/mcp”
      ]
    }
  }
}

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

🛠️ 開発

プロジェクト構造

google_workspace_mcp/
├── .venv/             # Virtual environment (created by uv)
├── auth/              # OAuth handling logic (google_auth.py, oauth_manager.py)
├── core/              # Core MCP server logic (server.py)
├── gcalendar/         # Google Calendar tools (calendar_tools.py)
├── gdocs/             # Google Docs tools (docs_tools.py)
├── gdrive/            # Google Drive tools (drive_tools.py)
├── gmail/             # Gmail tools (gmail_tools.py)
├── .gitignore         # Git ignore file
├── client_secret.json # Google OAuth Credentials (DO NOT COMMIT)
├── config.json        # Example mcpo configuration
├── main.py            # Main server entry point (imports tools)
├── mcp_server_debug.log # Log file for debugging
├── pyproject.toml     # Project metadata and dependencies (for uv/pip)
├── README.md          # This file
├── uv.lock            # uv lock file

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. 関数内で、認証された資格情報を取得します。

from auth.google_auth import get_credentials, CONFIG_CLIENT_SECRETS_PATH
# ...
credentials = await asyncio.to_thread(
    get_credentials,
    user_google_email=your_user_email_variable, # Optional, can be None if session_id is primary
    required_scopes=YOUR_SPECIFIC_SCOPES_LIST,  # e.g., [CALENDAR_READONLY_SCOPE]
    client_secrets_path=CONFIG_CLIENT_SECRETS_PATH,
    session_id=your_mcp_session_id_variable    # Usually injected via Header
)
if not credentials or not credentials.valid:
    # Handle missing/invalid credentials, possibly by calling start_auth_flow
    # from auth.google_auth (which is what service-specific start_auth tools do)
    pass

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ファイルを参照してください。