google-calendar

Google Calendar Workspace MCP Server

ドメイン全体の委任を使用したサービスアカウント認証による、Google Calendar 連携用の MCP（Model Context Protocol）サーバーです。このサーバーを使うと、AI アシスタントが Google Calendar と連携し、予定の一覧表示や作成、カレンダーの管理、空き状況の確認を行えます。

機能

• 予定の一覧表示：指定した期間内のカレンダーの予定を、フィルタリングして表示します
• 予定の詳細取得：特定の予定に関する完全な情報を取得します
• 予定の作成：参加者、場所、説明を指定して新しい予定を作成します
• 予定の更新：既存の予定を変更します（PATCH セマンティクス：指定したフィールドのみ更新されます）
• 予定の削除：参加者への通知を任意で行い、予定を削除します
• カレンダーの一覧表示：利用可能なカレンダーを確認します
• 空き状況の照会：空き状況を確認し、予定が入っている時間帯を特定します

前提条件

1. Calendar API が有効になっている Google Cloud プロジェクト
2. ドメイン全体の委任が有効な サービスアカウント
3. カレンダーの権限を付与するための Google Workspace 管理者 アクセス権

セットアップ

1. Google Cloud サービスアカウントを作成する

1. Google Cloud Console に移動します
2. プロジェクトを作成するか、選択します
3. Google Calendar API を有効にします：
   • 「APIs & Services」>「Library」に移動します
   • 「Google Calendar API」を検索します
   • 「Enable」をクリックします
4. サービスアカウントを作成します：
   • 「IAM & Admin」>「Service Accounts」に移動します
   • 「Create Service Account」をクリックします
   • 名前と説明を入力します
   • 「Create and Continue」をクリックします
   • ロールの付与はスキップします（ドメイン全体の委任には不要です）
   • 「Done」をクリックします
5. サービスアカウントのキーを作成します：
   • 作成したサービスアカウントをクリックします
   • 「Keys」タブに移動します
   • 「Add Key」>「Create new key」をクリックします
   • 「JSON」形式を選択します
   • キーファイルをダウンロードします
6. サービスアカウントの Client ID を確認します（サービスアカウントの詳細に記載されています）

2. ドメイン全体の委任を有効にする

1. サービスアカウントの詳細で、「Show domain-wide delegation」をクリックします
2. 「Enable Google Workspace Domain-wide Delegation」にチェックを入れます
3. 変更を保存します
4. Client ID を確認します（次の手順で必要になります）

3. Google Workspace 管理コンソールでカレンダーの権限を付与する

1. Google Workspace Admin Console に移動します
2. 「Security」>「Access and data control」>「API Controls」に移動します
3. 「Manage Domain Wide Delegation」をクリックします
4. 「Add new」をクリックします
5. サービスアカウントの Client ID を入力します
6. 「OAuth Scopes」欄に、次を追加します：

   https://www.googleapis.com/auth/calendar
   

7. 「Authorize」をクリックします

4. 環境変数を設定する

ダウンロードした JSON キーファイルから、次の値を取り出します：

• client_email：サービスアカウントのメールアドレス
• private_key：秘密鍵（-----BEGIN PRIVATE KEY----- と -----END PRIVATE KEY----- を含むもの）

次の環境変数を設定します：

export GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL="[email protected]"
export GCAL_SERVICE_ACCOUNT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYour private key content\n-----END PRIVATE KEY-----"
export GCAL_IMPERSONATE_EMAIL="[email protected]"

注記：GCAL_IMPERSONATE_EMAIL には、アクセスするカレンダーの所有者のメールアドレスを指定してください。

インストール

NPX を使用する（推奨）

npx google-calendar-workspace-mcp-server

NPM を使用する

npm install -g google-calendar-workspace-mcp-server
google-calendar-workspace-mcp-server

Claude Desktop での使用

この設定を Claude Desktop の設定ファイルに追加します：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["google-calendar-workspace-mcp-server"],
      "env": {
        "GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL": "[email protected]",
        "GCAL_SERVICE_ACCOUNT_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\nYour private key\n-----END PRIVATE KEY-----",
        "GCAL_IMPERSONATE_EMAIL": "[email protected]"
      }
    }
  }
}

ツールグループ

デフォルトでは、すべてのツールが有効になっています（読み取り＋書き込みアクセス）。ENABLED_TOOLGROUPS 環境変数を設定すると、サーバーを読み取り専用の操作に制限できます。

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["google-calendar-workspace-mcp-server"],
      "env": {
        "GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL": "...",
        "GCAL_SERVICE_ACCOUNT_PRIVATE_KEY": "...",
        "GCAL_IMPERSONATE_EMAIL": "...",
        "ENABLED_TOOLGROUPS": "readonly"
      }
    }
  }
}

利用可能なツールグループ：

グループ	含まれるツール
readwrite	7 つすべてのツール（読み取り＋書き込み）— デフォルトで含まれます
readonly	読み取り専用ツール：list_calendar_events、get_calendar_event、list_calendars、query_calendar_freebusy

readonly のみを使用する場合、書き込みツール（create_calendar_event、update_calendar_event、delete_calendar_event）は利用できません。

利用可能なツール

list_calendar_events

指定した場合は期間内の、カレンダーの予定一覧を取得します。

パラメーター：

• calendar_id（任意）：カレンダー ID（デフォルト：「primary」）
• time_min（任意）：RFC3339 形式の開始時刻
• time_max（任意）：RFC3339 形式の終了時刻
• max_results（任意）：取得する予定の最大数（デフォルト：10、最大：250）
• query（任意）：フリーテキストの検索クエリ
• single_events（任意）：繰り返しの予定を展開するかどうか（デフォルト：true）
• order_by（任意）：「startTime」または「updated」

例：

List my events for the next week

get_calendar_event

特定の予定の詳細情報を取得します。

パラメーター：

• event_id（必須）：予定 ID
• calendar_id（任意）：カレンダー ID（デフォルト：「primary」）

例：

Get details for event ID abc123

create_calendar_event

新しいカレンダーの予定を作成します。

パラメーター：

• summary（必須）：予定のタイトル
• start_datetime または start_date（必須）：予定の開始時刻
• end_datetime または end_date（必須）：予定の終了時刻
• description（任意）：予定の説明
• location（任意）：予定の場所
• attendees（任意）：メールアドレスの配列
• calendar_id（任意）：カレンダー ID（デフォルト：「primary」）

例：

Create a meeting tomorrow at 2pm for 1 hour titled "Team Sync"

update_calendar_event

既存のカレンダーの予定を更新します。PATCH セマンティクスを使用し、指定したフィールドのみが更新され、その他のフィールドは変更されません。

パラメーター：

• event_id（必須）：更新する予定の ID
• calendar_id（任意）：カレンダー ID（デフォルト：「primary」）
• summary（任意）：新しい予定のタイトル
• description（任意）：新しい予定の説明
• location（任意）：新しい予定の場所
• start_datetime または start_date（任意）：新しい開始時刻
• end_datetime または end_date（任意）：新しい終了時刻
• attendees（任意）：更新後の参加者のメールアドレスの配列
• send_updates（任意）：「all」、「externalOnly」、または「none」— 更新通知を送信するかどうか

例：

Update event abc123 to change the title to "Team Standup"

delete_calendar_event

カレンダーの予定を削除します。

パラメーター：

• event_id（必須）：削除する予定の ID
• calendar_id（任意）：カレンダー ID（デフォルト：「primary」）
• send_updates（任意）：「all」、「externalOnly」、または「none」— キャンセル通知を送信するかどうか

例：

Delete event abc123

list_calendars

認証済みユーザーが利用できるすべてのカレンダーを一覧表示します。

パラメーター：

• max_results（任意）：取得するカレンダーの最大数（デフォルト：50、最大：250）

例：

Show all my calendars

query_calendar_freebusy

カレンダーの空き状況を照会します。

パラメーター：

• time_min（必須）：RFC3339 形式の開始時刻
• time_max（必須）：RFC3339 形式の終了時刻
• calendar_ids（必須）：確認するカレンダー ID の配列
• timezone（任意）：照会に使用するタイムゾーン

例：

Check if I'm free tomorrow between 2pm and 4pm

開発

# Install dependencies
npm run install-all

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

# Run integration tests
npm run test:integration

# Run all tests
npm run test:all

セキュリティに関する考慮事項

• 秘密鍵のセキュリティ：サービスアカウントの秘密鍵をバージョン管理にコミットしないでください
• 最小権限：必要最小限の OAuth スコープのみを付与してください
• 鍵のローテーション：サービスアカウントの鍵を定期的にローテーションしてください
• アクセスログの記録：Google Cloud Console でサービスアカウントの使用状況を監視してください

トラブルシューティング

認証に失敗する

• サービスアカウントの認証情報が正しいことを確認してください
• ドメイン全体の委任が有効になっていることを確認してください
• Admin Console で正しい OAuth スコープが承認されていることを確認してください
• 偽装するメールアドレスが正しいことを確認してください

権限が拒否される

• Google Workspace Admin Console でカレンダーのスコープ（https://www.googleapis.com/auth/calendar）が付与されていることを確認してください
• 偽装するユーザーがカレンダーにアクセスできることを確認してください

カレンダーが見つからない

• カレンダー ID が正しいことを確認してください
• 偽装するユーザーがカレンダーにアクセスできることを確認してください
• list_calendars を使用して、利用可能なカレンダー ID を確認してください

ライセンス

MIT

貢献

ガイドラインについては、CONTRIBUTING.md を参照してください。