google-calendar

Google Calendar

Google Calendar を管理するツールです。イベントの作成、読み取り、更新、移動、削除、カレンダーの検索、カレンダーの一覧表示と作成、空き時間の確認、イベントの色パレットの解決、カレンダー共有（ACL）の管理ができます。Google Calendar API v3（https://www.googleapis.com/calendar/v3/）をラップしています。認証は単一の接続で OAuth 2.0 を使用します。利用可能な機能は、トークンの種類ではなく、スコープと各カレンダーのアクセス権限によって決まります。

Google Calendar 用の独立した非公式コネクターです。Google Calendar との提携、Google Calendar による承認や後援を受けていません。「Google Calendar」は所有者の商標であり、このコネクターが連携するサービスを識別する目的でのみ使用しています。

使用する場面

• エージェントがカレンダーのイベントを予定、検索、再調整、移動、キャンセルする必要がある場合。
• エージェントが、1 つ以上のカレンダーで誰かの予定が空いているかどうかを確認する必要がある場合。
• エージェントがカレンダーの一覧表示や作成、またはカレンダーのデフォルトのタイムゾーンの読み取りを行う必要がある場合。
• エージェントが誰かとカレンダーを共有したり、アクセス権を取り消したりする必要がある場合（ACL 管理。owner 権限が必要です）。

セットアップ

これは agentskills.io のスキルです。

コネクターがまだスキルとしてインストールされていない場合は、まず npx skills add zapier/connectors --skill google-calendar（または使用するハーネス独自のスキルインストール方法）でインストールしてから、ここに進んでください。スキルのインストールでコピーされるのはこれらのファイルであり、依存関係ではありません。CLI、ローカル MCP サーバー、または zapier-sdk の認証コマンドを実行する前に、ここで一度 npm install --omit=dev を実行してください。公開パッケージを依存関係として独自のプロジェクトにインポートする場合はどうでしょうか。その場合、npm install によってすべての依存関係が解決されます。詳しくは references/use-as-sdk.md を参照してください。

コネクターのテストを実行したり、references/ を確認したり、コネクターを改変したりするために、リポジトリのソースそのものが必要ですか。スコープを指定した git clone については README.md を参照してください。

コネクターの実行には Node.js 22.18+ が必要です。実行方法に合ったリファレンスを選び、ほかの作業を始める前に読み込んでください。

使用できるもの...	読み込むファイル
MCP 対応クライアント — ツールがすでに読み込まれている場合があります（例：mcp__google-calendar__<tool>）。またはローカルサーバーを自分で登録する（あるいはユーザーを案内する）こともできます	references/use-as-mcp.md
ターミナル／サブプロセスへのアクセス（node を実行できます）	references/use-as-cli.md
独自のコードのみ。このパッケージを依存関係としてインポートする場合	references/use-as-sdk.md
ツールもターミナルも使えず、このパッケージをインポートすることもできない場合 — Google Calendar API を直接呼び出す独自のコードを作成する場合（例：コード実行サンドボックス）	references/use-as-recipe.md

スクリプト

スクリプト	スクリプト名	接続	説明
scripts/createEvent.ts	createEvent	単一（"google-calendar"）	イベントを作成します（時間指定／終日、繰り返し、参加者、リマインダー、色、Google Meet）。
scripts/quickAddEvent.ts	quickAddEvent	単一（"google-calendar"）	簡単なテキスト文字列からイベントを作成します。タイトルと日時を解析します。
scripts/updateEvent.ts	updateEvent	単一（"google-calendar"）	イベントを部分的に更新します。配列フィールドは置き換えられます。ゲストを追加するには addEventAttendees を使用してください。
scripts/addEventAttendees.ts	addEventAttendees	単一（"google-calendar"）	既存の参加者を削除せずにイベントにゲストを追加します（読み取り・変更・書き込み）。
scripts/moveEvent.ts	moveEvent	単一（"google-calendar"）	イベントを別のカレンダーに移動します（デフォルトのイベントのみ）。
scripts/deleteEvent.ts	deleteEvent	単一（"google-calendar"）	イベントを削除します。べき等性があり、すでに削除済みのイベントも成功として報告されます。
scripts/listEvents.ts	listEvents	単一（"google-calendar"）	時間範囲、テキスト、イベントの種類でカレンダー上のイベントを一覧表示／検索します。
scripts/getEvent.ts	getEvent	単一（"google-calendar"）	ID で単一のイベントを取得します（解決済みの Google Meet リンクの確認などに使用します）。
scripts/listEventInstances.ts	listEventInstances	単一（"google-calendar"）	繰り返しイベントの各回を一覧表示します。単一の回を編集する際にインスタンス ID を解決します。
scripts/listCalendars.ts	listCalendars	単一（"google-calendar"）	ID、アクセス権限、メインカレンダーのフラグ、タイムゾーンを含むカレンダー一覧を表示します。メインの calendarId を解決します。
scripts/getCalendar.ts	getCalendar	単一（"google-calendar"）	カレンダーのメタデータを取得します。getCalendar("primary") はユーザーのデフォルトのタイムゾーンを返します。
scripts/createCalendar.ts	createCalendar	単一（"google-calendar"）	新しいサブカレンダーを作成します。
scripts/queryFreeBusy.ts	queryFreeBusy	単一（"google-calendar"）	指定した時間範囲について、1 つ以上のカレンダーの予定あり時間帯を返します。
scripts/getColors.ts	getColors	単一（"google-calendar"）	イベントとカレンダーのカラーパレットを返します（colorId のインデックス → 16 進数）。
scripts/listAclRules.ts	listAclRules	単一（"google-calendar"）	カレンダーの共有ルールを一覧表示します。owner ロールが必要です。
scripts/createAclRule.ts	createAclRule	単一（"google-calendar"）	指定したロールでユーザー／グループ／ドメインとカレンダーを共有します（または共有のロールを変更します）。owner が必要です。
scripts/deleteAclRule.ts	deleteAclRule	単一（"google-calendar"）	共有ルールを削除します（アクセス権を取り消します）。owner が必要です。
各スクリプトファイル内のスクリプトの inputSchema / outputSchema（Zod）が、契約の信頼できる情報源です。

曖昧さの解消と拒否

• 操作の前に対象を確認してください。 名前で検索したカレンダーやイベントに対して作成、移動、共有を行う前に、対象を確認してください。listCalendars で名前からカレンダーを特定する場合、大文字と小文字を区別せずに summary が完全一致するものを数えます。一致がちょうど1件ならそのカレンダーを対象に操作し、同数の候補が2件以上ある場合は操作を中止して、id と accessRole を含む候補を一覧表示し、どれを選ぶか尋ねてください。同じことは listEvents で特定するイベント（同じタイトルのイベントを複数登録している場合があります）と、listAclRules で特定する ACL ルールにも当てはまります。最初に一致したものを黙って選ばないでください。
• サポートされていない操作を偽装しないでください。 このコネクターは、カレンダーの名前変更や削除、カレンダーの全イベントの消去（calendars.clear）、外部で作成されたイベントのインポート（events.import）、1回の呼び出しでの「この回以降」の繰り返し予定の編集、トリガーや通知（watch チャネル）の設定には対応していません。これらの操作をユーザーから依頼された場合は、サポートされていないことを伝えて中止してください。別のツールで代用したり（例：「カレンダーを消去」するためにイベントを1件ずつ削除したり、「この回以降」を偽装するためにマスターをパッチしたり）、実行していない操作を成功したと報告したりしないでください。繰り返し予定の特定の1回については、listEventInstances → インスタンス ID に対する updateEvent を使用してください。

認証

すべてのシェイプで、認証情報そのものではなく、1つの接続セレクターとして [<resolver>:]<value> 文字列を渡します。すべてのコネクターで zapier:<connection-id>（Zapier 管理の認証。Zapier の認証、再試行、ガバナンスレイヤーを経由します）を使用できます。また、コネクターによっては1つ以上の直接トークンリゾルバーも使用できます（名前や数はコネクターごとに異なります）。推測せず、このコネクター独自のリゾルバーを確認してください。<resolver>: のプレフィックスは省略可能です。プレフィックスのない値は、それを受け付ける最初のリゾルバーに渡されます。UUID 形式のプレフィックスのない値は、必ず zapier: が受け付けます。各スクリプトには、必要な接続と、受け付けるリゾルバーが記載されています。接続を渡す正確な構文と、このコネクターのリゾルバー一覧の確認方法は、シェイプによって異なります。上記で読み込んだリファレンスを参照してください。

すでに設定済みの接続を先に確認しますか？そのために環境変数の値を出力しないでください。env や env | grep <name> は名前と値の両方を出力するため、値が設定されている場合、使用中の認証情報がトランスクリプトに漏えいします。名前だけを確認するには (env | cut -d= -f1 | grep -i <name>) を使用するか、既知の名前を直接テストしてください（[ -n "$VAR_NAME" ]）。

まだ接続がありませんか？いずれかを選び、接続を取得する際はリファレンスに記載された手順に従ってください。ユーザーに接続 ID やトークンを、すでに覚えているかのように尋ねないでください。

	読み込み
認証情報を直接渡す	references/use-without-zapier.md
Zapier 接続を経由して渡す	references/use-with-zapier.md

出力形式

すべてのスクリプトは { data, meta } エンベロープを返します。

• data — スクリプトの結果です（その outputSchema が宣言する形式です。スクリプトの正確なスキーマを確認する方法については、上で読み込んだリファレンスを参照してください）。
• meta.outputDataValidation — data の検証結果です。
  • { skipped: false, droppedPaths: null } — 検証済みで、削除されたものはありません。
  • { skipped: false, droppedPaths: [...], instruction } — 検証済みですが、該当するパスは data から取り除かれました。スクリプトが API から返したフィールドのうち、outputSchema で宣言されていないものです。これらが必要な場合は、出力検証をスキップして再実行してください。
  • { skipped: true } — 検証はスキップされ、data は未検証のスクリプト出力そのものです。

削除されたフィールドの確認／skipOutputDataValidation。 未検証の生の結果を受け取るには、出力検証を無効にします（正確な構文は形状によって異なります。上で読み込んだリファレンスを参照してください）。入力検証はスキップされません。

結果のトリミング／filterOutputData。 大きな結果を必要なフィールドに絞るには、data を後処理する jq 式を渡します（正確な構文は形状によって異なります）。jq は { data, meta } エンベロープではなく data のみに対して実行されるため、data を起点として記述してください（出力スキーマを確認するには、スクリプトの --help、または形状に応じた同等のコマンドを実行してください）。変換後の値が data に置き換わり、meta は保持されます。また、結果は出力スキーマに対して再検証されません。

リファレンス

該当する領域で作業する前に、対応するリファレンスファイルを読み込んでください。

リファレンス	対象	読み込むタイミング
google-calendar-api-gotchas.md	エラーエンベロープと復旧方法、終日イベントの排他的な end.date、繰り返し予定で必須となる timeZone、イベントタイプの作成制約、非同期の Meet 作成、ページネーションの上限、カレンダーごとの空き時間／予定ありエラー、ACL のオーナーロール規則。	イベントの日付／時刻、繰り返し予定、色、Google Meet リンクを設定する前、401／403／404／410 エラーの処理時、イベントの更新時（配列フィールドは全置換）、またはカレンダーの共有時（ACL）。