Google Workspace MCP

🚀 Google Workspace MCP Server

このサーバーは、Google Workspaceの主要なサービスをAIアシスタントと統合した、機能が充実したMCPサーバーです。FastMCPを用いて構築され、最適なパフォーマンスを発揮します。また、高度な認証処理、サービスキャッシュ、効率的な開発パターンを備えています。

🚀 クイックスタート

1. ワンクリックClaudeデスクトップインストール (推奨)

1. ダウンロード: 「Releases」ページから最新のgoogle_workspace_mcp.dxtをダウンロードします。
2. インストール: ファイルをダブルクリックすると、Claudeデスクトップが開き、「インストール」を求めるプロンプトが表示されます。
3. 設定: Claudeデスクトップ → 「設定」 → 「拡張機能」 → 「Google Workspace MCP」で、Google OAuthの資格情報を貼り付けます。
4. 使用: 新しいClaudeチャットを開始し、任意のGoogle Workspaceツールを呼び出せます。

なぜDXTを使うのか？ デスクトップ拡張機能 (.dxt) は、サーバー、依存関係、マニフェストをバンドルしているため、ユーザーはダウンロードから動作するMCPまでをワンクリックで完了できます。ターミナル操作やJSON編集、バージョンの競合を心配する必要はありません。

必要な設定

2. 高度な/クロスプラットフォームインストール

開発やサーバーへのデプロイ、または他のMCP対応クライアントを使用する場合は、以下を読んでください。

インスタントCLI (uvx)

# Python 3.11+ と uvx が必要です
export GOOGLE_OAUTH_CLIENT_ID="xxx"
export GOOGLE_OAUTH_CLIENT_SECRET="yyy"
uvx workspace-mcp --tools gmail drive calendar

手動でのインストールなしに即座に実行できます。uvxを使用する場合はOAuth資格情報を設定する必要があります。環境変数 (本番環境で推奨) または GOOGLE_CLIENT_SECRET_PATH (またはレガシーの GOOGLE_CLIENT_SECRETS) 環境変数を使用して client_secret.json ファイルを指定できます。

# 環境変数を使用してOAuth資格情報を設定 (推奨)
export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"

# すべてのGoogle Workspaceツールでサーバーを起動
uvx workspace-mcp

# 特定のツールのみで起動
uvx workspace-mcp --tools gmail drive calendar tasks

# デバッグ用のHTTPモードで起動
uvx workspace-mcp --transport streamable-http

Python 3.11+ と uvx が必要です。このパッケージは PyPI で利用可能です。

開発用インストール

開発またはカスタマイズする場合は、以下のコマンドを実行します。

git clone https://github.com/taylorwilsdon/google_workspace_mcp.git
cd google_workspace_mcp
uv run main.py

前提条件

• Python 3.11+
• uvx (インスタントインストール用) または uv (開発用)
• OAuth 2.0資格情報を持つGoogle Cloudプロジェクト

設定

1. Google Cloudの設定:

   • Google Cloud Console でOAuth 2.0資格情報 (ウェブアプリケーション) を作成します。

   • APIを有効にします: Calendar, Drive, Gmail, Docs, Sheets, Slides, Forms, Tasks, Chat

   • リダイレクトURIを追加します: http://localhost:8000/oauth2callback

   • 以下の方法のいずれかを使用して資格情報を設定します。

     オプションA: 環境変数 (本番環境で推奨)

     export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
     export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"
     export GOOGLE_OAUTH_REDIRECT_URI="http://localhost:8000/oauth2callback"  # オプション
     

     オプションB: ファイルベース (従来の方法)

     • 資格情報を client_secret.json としてプロジェクトルートにダウンロードします。
     • 別の場所を使用する場合は、GOOGLE_CLIENT_SECRET_PATH (またはレガシーの GOOGLE_CLIENT_SECRETS) 環境変数にファイルパスを設定します。

   資格情報の読み込み優先順位:

   1. 環境変数 (GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET)
   2. GOOGLE_CLIENT_SECRET_PATH または GOOGLE_CLIENT_SECRETS 環境変数で指定されたファイル
   3. デフォルトファイル (プロジェクトルートの client_secret.json)

   なぜ環境変数を使うのか？

   • ✅ コンテナ化されたデプロイ (Docker, Kubernetes)
   • ✅ クラウドプラットフォーム (Heroku, Railwayなど)
   • ✅ CI/CDパイプライン
   • ✅ バージョン管理にシークレットを含めない
   • ✅ 資格情報のローテーションが容易

2. 環境設定:

   export OAUTHLIB_INSECURE_TRANSPORT=1  # 開発環境のみ
   export USER_GOOGLE_EMAIL=your.email@gmail.com  # オプション: 認証のデフォルトメールアドレス - シングルユーザー設定で使用すると、マジック認証のシステムプロンプトでメールアドレスを設定する必要がなくなります
   

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

   • WORKSPACE_MCP_BASE_URI: サーバーのベースURIを設定します (デフォルト: http://localhost)。これは、GOOGLE_OAUTH_REDIRECT_URI が設定されていない場合に、デフォルトの OAUTH_REDIRECT_URI を構築するために使用される server_url に影響します。
   • WORKSPACE_MCP_PORT: サーバーがリッスンするポートを設定します (デフォルト: 8000)。これは、server_url、port、およびOAUTH_REDIRECT_URIに影響します。
   • USER_GOOGLE_EMAIL: 認証フローのオプションのデフォルトメールアドレス。設定すると、LLMが start_google_auth を呼び出すときにメールアドレスを指定する必要がなくなります。
   • GOOGLE_OAUTH_REDIRECT_URI: OAuthリダイレクトを特別にオーバーライドします。完全なアドレスを含める必要があります (必要に応じてポートを含める)。MCPとは別にOAuthリダイレクトを実行したい場合に使用します。非常に特殊なケース以外は推奨されません。

サーバーの起動

# デフォルト (MCPクライアント用のstdioモード)
uv run main.py

# HTTPモード (ウェブインターフェースとデバッグ用)
uv run main.py --transport streamable-http

# シングルユーザーモード (簡易認証)
uv run main.py --single-user

# 選択的なツール登録 (特定のツールのみを登録)
uv run main.py --tools gmail drive calendar tasks
uv run main.py --tools sheets docs
uv run main.py --single-user --tools gmail  # 他のフラグと組み合わせることができます

# Docker
docker build -t workspace-mcp .
docker run -p 8000:8000 -v $(pwd):/app workspace-mcp --transport streamable-http

--tools フラグで利用可能なツール: gmail, drive, calendar, docs, sheets, forms, tasks, chat

Claudeデスクトップへの接続

サーバーは2つのトランスポートモードをサポートしています。

Stdioモード (デフォルト - Claudeデスクトップに推奨)

ガイド付きセットアップ (DXTを使用しない場合に推奨)

python install_claude.py

このスクリプトは自動的に以下を行います。

• Google OAuth資格情報 (クライアントIDとシークレット) を入力するように促します。
• Claudeデスクトップの設定ファイルを正しい場所に作成します。
• 必要なすべての環境変数を設定します。
• 手動でのファイル編集は必要ありません！

スクリプトを実行した後、Claudeデスクトップを再起動すると、すぐに使用できます。

手動でのClaude設定 (代替方法)

1. Claudeデスクトップの設定 → 開発者 → 設定の編集を開きます。
   1. macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   2. Windows: %APPDATA%\Claude\claude_desktop_config.json
2. サーバーの設定を追加します。

   {
     "mcpServers": {
       "google_workspace": {
         "command": "uvx",
         "args": ["workspace-mcp"],
         "env": {
           "GOOGLE_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
           "GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret",
           "OAUTHLIB_INSECURE_TRANSPORT": "1"
         }
       }
     }
   }
   

Google OAuth資格情報の取得 (持っていない場合):

• Google Cloud Console にアクセスします。
• 新しいプロジェクトを作成し、APIを有効にします: Calendar, Drive, Gmail, Docs, Sheets, Slides, Forms, Tasks, Chat
• リダイレクトURIが http://localhost:8000/oauth2callback のOAuth 2.0クライアントID (ウェブアプリケーション) を作成します。

開発用インストール (貢献者向け):

{
  "mcpServers": {
    "google_workspace": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/repo/google_workspace_mcp",
        "main.py"
      ],
      "env": {
        "GOOGLE_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret",
        "OAUTHLIB_INSECURE_TRANSPORT": "1"
      }
    }
  }
}

HTTPモード (デバッグまたはウェブインターフェース用)

ClaudeデスクトップでHTTPモードを使用する必要がある場合は、以下の設定を行います。

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

注: HTTPモードを使用する場合は、サーバーを --transport streamable-http で起動する必要があります。

初回認証

サーバーはトランスポートに対応したOAuthコールバック処理を備えています。

• Stdioモード: OAuthコールバック用にポート8000で最小限のHTTPサーバーを自動的に起動します。
• HTTPモード: 既存のFastAPIサーバーをOAuthコールバックに使用します。
• 同じOAuthフロー: 両方のモードで一貫性を保つために、http://localhost:8000/oauth2callback を使用します。

ツールを呼び出すとき:

1. サーバーが認証URLを返します。
2. ブラウザでURLを開き、承認します。
3. サーバーがOAuthコールバックを自動的に処理します (両方のモードでポート8000)。
4. 元のリクエストを再試行します。

✨ 主な機能

• 🔐 高度なOAuth 2.0: 自動トークン更新、トランスポートに対応したコールバック処理、セッション管理、および集中的なスコープ管理を備えた安全な認証
• 📅 Google Calendar: イベントのCRUD操作を含む完全なカレンダー管理
• 📁 Google Drive: ネイティブのMicrosoft Office形式 (.docx, .xlsx) をサポートするファイル操作
• 📧 Gmail: 検索、送信、下書き機能を備えた完全なメール管理
• 📄 Google Docs: コンテンツの抽出、作成、コメント管理を含むドキュメント操作
• 📊 Google Sheets: 柔軟なセル操作とコメント管理を備えた包括的なスプレッドシート管理
• 🖼️ Google Slides: スライドの作成、更新、コンテンツ操作、コメント管理を含むプレゼンテーション管理
• 📝 Google Forms: フォームの作成、取得、公開設定、および応答管理
• ✓ Google Tasks: 階層、期限、ステータス追跡を備えた完全なタスクとタスクリスト管理
• 💬 Google Chat: スペース管理とメッセージング機能
• 🔄 すべてのトランスポート: Stdio、Streamable HTTP & SSE、mcpo を介したOpenAPI互換性
• ⚡ 高パフォーマンス: サービスキャッシュ、スレッドセーフなセッション、FastMCP統合
• 🧩 開発者にやさしい: 最小限のボイラープレート、自動サービス注入、集中的な設定

🧰 利用可能なツール

注意: すべてのツールは、@require_google_service() デコレータを介した自動認証をサポートし、30分間のサービスキャッシュがあります。

📅 Google Calendar (calendar_tools.py)

📁 Google Drive (drive_tools.py)

📧 Gmail (gmail_tools.py)

📝 Google Docs (docs_tools.py)

📊 Google Sheets (sheets_tools.py)

🖼️ Google Slides (slides_tools.py)

📝 Google Forms (forms_tools.py)

✓ Google Tasks (tasks_tools.py)

💬 Google Chat (chat_tools.py)

🛠️ 開発

プロジェクト構造

google_workspace_mcp/
├── auth/              # デコレータ付きの認証システム
├── core/              # MCPサーバーとユーティリティ
├── g{service}/        # サービス固有のツール
├── main.py            # サーバーのエントリポイント
├── client_secret.json # OAuth資格情報 (コミットされない)
└── pyproject.toml     # 依存関係

新しいツールの追加

from auth.service_decorator import require_google_service

@require_google_service("drive", "drive_read")  # サービス + スコープグループ
async def your_new_tool(service, param1: str, param2: int = 10):
    """ツールの説明"""
    # サービスは自動的に注入され、キャッシュされます
    result = service.files().list().execute()
    return result  # ネイティブのPythonオブジェクトを返す

アーキテクチャのハイライト

• サービスキャッシュ: 30分のTTLで認証のオーバーヘッドを削減します。
• スコープ管理: SCOPE_GROUPS で集中管理され、保守が容易です。
• エラー処理: 手動でのエラー構築ではなく、ネイティブの例外を使用します。
• マルチサービスサポート: 複雑なツールに @require_multiple_services() を使用します。

🔒 セキュリティ

• 資格情報: client_secret.json または .credentials/ ディレクトリを決してコミットしないでください。
• OAuthコールバック: 開発用に http://localhost:8000/oauth2callback を使用します ( OAUTHLIB_INSECURE_TRANSPORT=1 が必要)。
• トランスポートに対応したコールバック: StdioモードではOAuth用に最小限のHTTPサーバーを起動し、すべてのモードでコールバックが機能するようにします。
• 本番環境: コールバックURIにHTTPSを使用し、適切に構成します。
• ネットワーク露出: mcpo をネットワーク経由で使用する場合は、認証を考慮してください。
• スコープの最小化: ツールは必要な権限のみを要求します。

🌐 Open WebUIとの統合

このサーバーをOpen WebUI内のツールプロバイダーとして使用するには、以下の手順を実行します。

即座に開始 (設定不要)

以下をコピーして貼り付け、値を設定するとすぐに使用できます！

GOOGLE_OAUTH_CLIENT_ID="your_client_id" GOOGLE_OAUTH_CLIENT_SECRET="your_client_secret" uvx mcpo --port 8000 --api-key "top-secret" -- uvx workspace-mcp

それ以外の場合は、以下の手順を実行します。

1. MCPO設定の作成

mcpo がストリーマブルHTTPエンドポイントをOpenAPI仕様ツールとして利用可能にするために、以下の構造の config.json ファイルを作成します。

{
  "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の設定

1. Open WebUIの設定に移動します。
2. "接続" → "ツール" に移動します。
3. "ツールの追加" をクリックします。
4. サーバーURLを入力します: http://localhost:8001/google_workspace (config.jsonのmcpoベースURLとサーバー名に一致)
5. --api-key をmcpoで使用した場合は、それをAPIキーとして入力します。
6. 設定を保存します。

これで、Open WebUIでモデルと対話する際にGoogle Workspaceツールが利用可能になります。

📄 ライセンス

MITライセンス - 詳細は LICENSE ファイルを参照してください。