Google Workspace MCP サーバー

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

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

📑 目次

🌐 概要

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 .

構成

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

サービス	デフォルトポート	説明
OAuthコールバック	`8000`	`/oauth2callback`ルート経由でサーバー内部で処理される
HTTPモードサーバー	`8000`	HTTPトランスポートを使用する場合のデフォルト

サーバーへの接続

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

クロードデスクトップ:

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

config.json:

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

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

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

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

Open WebUIとの統合

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

mcpo構成の作成: 次の構造を持つconfig.jsonという名前のファイルを作成し、mcpo がストリーミング可能な HTTP エンドポイントを OpenAPI 仕様ツールとして使用できるようにします。
{ "mcpServers": { "google_workspace": { "type": "streamablehttp", "url": "http://localhost:8000/mcp" } } }
mcpoサーバーを起動します。
mcpo --port 8001 --config config.json --api-key "your-optional-secret-key"
このコマンドはmcpoプロキシを起動し、アクティブな（ポート 8000 と想定）Google Workspace MCP をポート 8001 で提供します。
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 を取得した後):

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

🧰 利用可能なツール

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

📅 Googleカレンダー

ソース: gcalendar/calendar_tools.py

道具	説明	パラメータ
`start_google_auth`	（ `core/server.py`に集約）特定のGoogleアカウントとサービスに対してOAuth 2.0認証フローを開始します。有効な認証情報が利用できない場合、または認証情報がなくツールが失敗した場合や、メールアドレスが提供されていない場合に使用します。	• `user_google_email` （必須）: ユーザーのGoogleメールアドレス• `service_name` （必須）: Googleサービス名（例：「Googleカレンダー」、「Googleドキュメント」、「Gmail」、「Googleドライブ」）
`list_calendars`	認証されたユーザーがアクセスできるすべてのカレンダーを一覧表示します。	• `user_google_email` （オプション）：セッションが認証されていない場合に使用されます。• `mcp_session_id` （自動的に挿入されます）
`get_events`	指定されたカレンダーから時間範囲内の今後のイベントを取得します。	• `calendar_id` （オプション）：カレンダーID（デフォルト： `primary` ）• `time_min` （オプション）：開始時刻（RFC3339または`YYYY-MM-DD` ）• `time_max` （オプション）：終了時刻（RFC3339または`YYYY-MM-DD` ）• `max_results` （オプション）：イベントの最大数（デフォルト：25）• `user_google_email` （オプション）• `mcp_session_id` （自動的に挿入されます）
`create_event`	新しいカレンダーイベントを作成します。終日イベントと時間指定イベントをサポートします。	• `summary` （必須）: イベントタイトル• `start_time` （必須）: 開始時刻（RFC3339 または`YYYY-MM-DD` ）• `end_time` （必須）: 終了時刻（RFC3339 または`YYYY-MM-DD` ）• `calendar_id` （オプション）: カレンダーID（デフォルト： `primary` ）• `description` 、 `location` 、 `attendees` 、 `timezone` （オプション）• `user_google_email` （オプション）• `mcp_session_id` （自動的に挿入されます）
`modify_event`	既存のイベントをIDで更新します。指定されたフィールドのみが変更されます。	• `event_id` （必須）: 変更するイベントのID• `calendar_id` （オプション）: カレンダーID（デフォルト： `primary` ）• `summary` 、 `start_time` 、 `end_time` 、 `description` 、 `location` 、 `attendees` 、 `timezone` （オプション）• `user_google_email` （オプション）• `mcp_session_id` （自動的に挿入されます）
`delete_event`	ID でイベントを削除します。	• `event_id` （必須）: 削除するイベントのID• `calendar_id` （オプション）: カレンダーID（デフォルト： `primary` ）• `user_google_email` （オプション）• `mcp_session_id` （自動的に挿入されます）

ℹ️ すべてのカレンダーツールは、現在の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

道具	説明	パラメータ
`search_drive_files`	ユーザーのドライブ全体でファイルとフォルダを検索します	• `query` (必須): 検索クエリ文字列 (例: `name contains 'report'` ) • `max_results` (オプション): 返されるファイルの最大数
`get_drive_file_content`	特定のファイルの内容を取得します	• `file_id` （必須）: ファイルのID• `mime_type` （オプション）: 希望するエクスポート形式を指定します
`list_drive_items`	特定のフォルダまたはルート内のファイルとフォルダを一覧表示します	• `folder_id` （オプション）：一覧表示するフォルダのID（デフォルトはルート）• `max_results` （オプション）：返されるアイテムの最大数
`create_drive_file`	Googleドライブに新しいファイルを作成します	• `name` (必須): 新しいファイルの名前• `content` (必須): ファイルに書き込むテキストコンテンツ• `folder_id` (オプション): 親フォルダのID• `mime_type` (オプション): ファイルのMIMEタイプ（デフォルトは`text/plain` ）

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

📧 Gメール

ソース: gmail/gmail_tools.py

道具	説明	パラメータ
`search_gmail_messages`	標準の Gmail 検索演算子 (送信元、件名など) を使用してメールメッセージを検索します。	• `query` （必須）: 検索文字列（例： `"from:foo subject:bar is:unread"` ）• `user_google_email` （オプション）• `page_size` （オプション、デフォルト：10）• `mcp_session_id` （自動的に挿入されます）
`get_gmail_message_content`	メッセージ ID で電子メールの件名、送信者、プレーンテキスト本文を取得します。	• `message_id` （必須）• `user_google_email` （オプション）• `mcp_session_id` （自動的に挿入されます）
`send_gmail_message`	ユーザーの Gmail アカウントを使用してプレーンテキストメールを送信します。	• `to` (必須): 受信者のメールアドレス• `subject` (必須)• `body` (必須)• `user_google_email` (オプション)• `mcp_session_id` (自動的に挿入されます)
`draft_gmail_message`	ユーザーの Gmail アカウントに下書きメールを作成します。	• `subject` （必須）: メールの件名• `body` （必須）: メールの本文（プレーンテキスト）• `to` （オプション）: 受信者のメールアドレス• `user_google_email` （オプション）• `mcp_session_id` （自動的に挿入されます）

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

📝 Google ドキュメント

出典: gdocs/docs_tools.py

道具	説明	パラメータ
`search_docs`	Google ドキュメントを名前で検索します (Drive API を使用)。	• `query` （必須）: ドキュメント名で検索するテキスト• `user_google_email` （オプション）• `page_size` （オプション、デフォルト：10）• `mcp_session_id` （自動的に挿入されます）
`get_doc_content`	ドキュメント ID で Google ドキュメントのプレーンテキストコンテンツを取得します。	• `document_id` （必須）• `user_google_email` （オプション）• `mcp_session_id` （自動的に挿入されます）
`list_docs_in_folder`	指定されたドライブフォルダ内のすべての Google ドキュメントを一覧表示します (フォルダ ID 別、デフォルト = `root` )。	• `folder_id` （オプション、デフォルト: `'root'` ）• `user_google_email` （オプション）• `page_size` （オプション、デフォルト: 100）• `mcp_session_id` （自動的に挿入されます）
`create_doc`	オプションで初期コンテンツを含む新しい Google ドキュメントを作成します。	• `title` （必須）：ドキュメントの名前• `content` （オプション、デフォルト：空）• `user_google_email` （オプション）• `mcp_session_id` （自動的に挿入されます）

🛠️ 開発

プロジェクト構造

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 から返されたトレースバックまたはエラーメッセージがないか、サーバーログを確認します。

新しいツールの追加

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

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

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

Google Workspace MCP Server