google-calendar-mcp

google-calendar-mcp

Google Calendar 用の MCP サーバーです。1 つのバイナリで動作し、stdio を使用して、ご自身の Google アカウントでユーザーごとの OAuth 認証を行います。

これは、カレンダー、その予定、そして誰が空いているかという いつ に答えます。会議で生成されるもの（録画、メモのドキュメント、添付ファイル）は、Meet、Docs、Drive API を基盤とするサーバーが扱います。get_event は予定に添付されたファイルの名前と、そのサーバーが使用する Drive ファイル ID を返します。

このツールならではの特長

LLM が利用する多くのカレンダーツールには、微妙ながらも重要な誤りが 3 つあります。このサーバーはそうした誤りを防ぐように設計されており、それぞれを注意に頼るのではなく、テストで検証しています。

• 終日の予定は時刻ではなく日付です。 そのため、時点に変換されることはなく、UTC より西にいる人にとって別の日に表示されることもありません。時刻指定の予定にはすべて、単なるオフセットではなく実際の IANA タイムゾーンが設定されます。オフセットだけでは、夏時間の変更をまたぐ繰り返し予定を展開できないためです。
• すべての読み取り結果に、読み取った内容が示されます。 絶対時間の範囲、タイムゾーン、その取得元、リストが途中で切り詰められたかどうかが含まれます。どの木曜日を表示しているのか示されないスケジュールは、どの木曜日としても解釈できてしまいます。
• 空き状況は予定のリストではありません。 詳細を確認できない予定でも、その人は予定ありになります。一方、「空き」とマークされた予定は予定ありにはなりません。読み取れなかったカレンダーは「空き」に含めず、不明 として報告します。

設計、その根拠の記録、フェーズ計画については、docs/architecture.md を参照してください。

ステータス

読み取り、書き込み、繰り返し、空き状況、カレンダー、共有、リソース、Claude Desktop バンドルが完成し、運用中です。ツールは以下に記載しています。フェーズ計画と未対応事項については、docs/architecture.md §16 を参照してください。

インストール

go install github.com/mmedum/google-calendar-mcp/v3/cmd/google-calendar-mcp@latest

または、リリースページからアーカイブをダウンロードしてください。

セットアップ

ご自身の Google Cloud プロジェクトと OAuth クライアントが必要です。このリポジトリには、特定のデプロイ環境向けの設定は含まれていません。

1. プロジェクトを作成し、Google Calendar API を有効にします。
2. OAuth 同意画面を設定し、docs/gcp-setup.md に記載されたスコープを追加します。このファイルはコードから生成されるため、ツールの仕様から取り残されることはありません。
3. デスクトップアプリ タイプの OAuth クライアントを作成し、JSON をダウンロードします。
4. サインインします。

google-calendar-mcp login --client-secret ~/path/to/client_secret.json
google-calendar-mcp doctor

doctor はクライアント JSON、保存済みトークン、付与されたスコープ、API が応答するかどうかを確認し、不足しているものを示します。

SSH 経由でのサインイン

OAuth コールバックは、login を実行しているマシンのループバックインターフェースに届きますが、ブラウザーはご自身のマシン上にあります。まずポートフォワーディングを設定してください。--no-browser を指定すると、認証 URL と、実際に選ばれたポートを使って実行する正確な ssh -L コマンドが表示されます。

MCP クライアントを設定する

{
  "mcpServers": {
    "google-calendar": {
      "command": "google-calendar-mcp",
      "env": {
        "GCAL_CLIENT_SECRET": "/path/to/client_secret.json"
      }
    }
  }
}

各設定項目については、docs/configuration.md を参照してください。

ツール

ツール	内容
list_calendars	このアカウントから参照できるすべてのカレンダーと、その ID、タイムゾーン、アクセスレベルを表示します。まずはこちらを使ってください。
get_calendar	1 つのカレンダーの詳細を表示します。共有相手とデフォルトのリマインダーも含まれます。
list_events	指定した期間内に 1 つ以上のカレンダーで予定されているイベントを表示します。または、不在など、指定した種類のイベントだけや、招待メールについてのイベントだけを表示します。
search_events	指定した期間内のタイトル、説明、場所、ゲストを対象に、フリーテキストで検索します。
get_event	1 つのイベントの詳細を表示します。ゲストとその回答、ゲストができる操作、自分のリマインダー、添付ファイルも含まれます。
list_instances	1 つの繰り返しイベントの各回と、日付が変更または削除された回を表示します。
list_changes	前回確認した後に変更された内容を表示します。削除も含まれます。削除されたイベントは検索条件に一致しなくなるため、通常の一覧では報告できません。次回渡す同期トークンを返すか、指定した時点以降の変更を取得します。
check_availability	イベント一覧ではなく、Google の空き時間情報サービスから、ユーザーが予定ありの時間と空き時間を取得します。任意で勤務時間のマスクを指定できます。
get_settings	アカウントのタイムゾーン、週の開始曜日、カラーパレットを表示します。
create_event	ゲスト、任意参加のゲスト、会議室、リマインダー、公開設定、ゲストができる操作を指定して、単発または繰り返しイベントを作成します。リクエストすれば Google Meet のリンクも追加できます。または、メインカレンダーに不在、集中時間、勤務場所のステータスイベントを作成します。
update_event	リマインダー、公開設定、ゲストができる操作を含め、イベントを変更するか、Google Meet のリンクを追加します。渡したフィールドだけが変更されます。
cancel_event	イベント、または繰り返しイベントの 1 回分をキャンセルします。
move_event	イベントを別のカレンダーに移動します。主催者が変わります。
respond_to_event	招待に承諾、辞退、または仮承諾で回答します。
create_calendar	自分のカレンダーを作成します。
manage_calendar	カレンダーの名前やタイムゾーンを変更する、自分用の色や名前を設定する、または一覧への追加・削除を行います。
list_sharing	カレンダーを閲覧できるユーザーと、それぞれが閲覧できる内容を表示します。
share_calendar	ユーザーにアクセス権を付与するか、既存のアクセス権を変更します。
unshare_calendar	ユーザーのアクセス権を取り消します。
delete_calendar	カレンダーと、そのカレンダー上のすべてのイベントを削除します。ゲートで保護されています。
clear_calendar	メインカレンダー上のすべてのイベントを削除します。ゲートで保護されています。

GCAL_READONLY=true を設定すると最初の 9 つのツールが登録され、読み取り専用スコープのみが要求されるため、API 自体が書き込みを拒否します。

manage_calendar は、API では 2 つのリソースに分かれていて、通常は区別されないものを扱います。共有相手全員に表示されるのはカレンダー（タイトル、説明、場所、タイムゾーン）であり、そのカレンダーへの自分の登録情報（色、自分が付けた名前、非表示にするかどうか、メールで通知を受ける内容）は自分だけのものです。登録を解除すると自分の一覧から削除されますが、カレンダーは削除されず、他のユーザーにも気付かれません。

すべての書き込みには、調査対象のサーバーで見られるような推測を防ぐため、次の 3 つのルールが適用されます。

• 書き込みが他のユーザーに届く可能性がある場合、notify は必須で、どちらの方向にもデフォルト値はありません。ゲストが組織外にいる場合、none は明示的に拒否されます。そのゲストはイベントを表示する Google Calendar を持っていない可能性があり、イベントを知る手段がメールしかないためです。
• イベントが繰り返される場合、scope は必須です。指定できる値は instance、series、this_and_following です。「定例会議を 10:30 に移動する」は 3 通りの異なる操作ですが、API では同じもののように扱われます。
• すべての書き込みは If-Match を使ったパッチであり、先に誰かが変更していた場合は上書きせず、[stale] として拒否されます。ゲストを追加する際は一覧を読み取って追加するため、既存の一覧が置き換えられることはありません。

いずれかのツールで dry_run: true を指定すると、書き込みは行わず、変更内容とメールが送信されるゲストの人数を報告します。 200 人を超えるゲストがいる場合、Google は個々の回答の伝播を停止するため、そのようなイベントに関するすべての結果には、表示される RSVP は不完全であると記載されます。

リソース

ツールを呼び出すのではなくコンテキストを添付するクライアント向けに、同じ内容が次の 3 つのリソースとして公開されています。

URI	内容
gcal://calendars	カレンダーの一覧です。list_calendars の返す内容と同じです。
gcal://calendars/{calendar_id}	1 つのカレンダーです。get_calendar の返す内容と同じです。
gcal://calendars/{calendar_id}/events/{event_id}	1 つのイベントです。get_event の返す内容と同じです。

これらはハンドルを持たず、引数も受け取りません。そのため、スケジュール用のリソースはありません。時間枠とタイムゾーンはここでは省略できず、それらを指定する場所のない URI では、どちらも独自に決める必要があるからです。

勤務時間

check_availability は時間枠を対象に回答します。時間枠は 1 つの区間なので、「来週の 09:00 から 17:00 まで」を 1 回で尋ねることはできません。また、回答に含まれる最長の空き時間は 15 時間の夜間区間であり、どのような min_minutes を指定しても条件を満たします。working_from、working_to、working_days を指定すると、勤務週に合わせて空き時間を絞り込めます。デフォルト値はありません。これらを指定しない場合は時間枠内のすべての時間が対象となり、結果には常に使用された設定が示されます。絞り込みは、回答を表示するタイムゾーンで、現地の日ごとに適用されるため、時計が切り替わる日曜日でも 09:00 は 09:00 のままです。

会議リンク

create_event は conference: true を受け取り、Google Meet のリンクを Google に要求します。通常、このリンクはイベントとともに返されます。Google の説明では、会議は非同期で生成されるため、結果には生成中と表示される場合があり、その場合はイベントを再度読み取ります。どちらの場合も、結果には状況が示され、存在しないリンクが報告されることはありません。update_event は add_conference を受け取り、会議リンクのないイベントにリンクを追加します。

安全性

• Calendar が元に戻せない操作を行う 2 つのツール、delete_calendar と clear_calendar は、GCAL_ENABLE_DESTRUCTIVE=true が設定されていない限り登録されません。また、どちらも呼び出し時に confirm: true が必要です。cancel_event は意図的にこのフラグの対象外です。会議のキャンセルはカレンダーの本来の用途であり、Google は記録を保持します。誰もが有効にするゲートでは誰も守れません。その理由は docs/architecture.md §9 で説明されています。代わりに、必須の scope と notify が保護策になっています。
• notify: none を指定してキャンセルすると、会議は自分のカレンダーから削除されますが、ゲストのカレンダーには残ります。結果には毎回その旨が記載されます。
• ここでアカウント外に影響が及ぶ唯一の操作が共有であるため、share_calendar は他のすべての書き込みと同様に notify を必須とします。ただし、この場合、Google のデフォルト設定はメール送信であり、イベントの場合とは逆です。「全員」と共有すると、カレンダーがインターネット全体に公開されるため、allow_public: true が必要です。その後ルールを削除すると、新たな閲覧者はアクセスできなくなりますが、すでに閲覧した人から見た内容を取り消すことはできません。アクセス権を削除しても、Google には通知する方法がないため、誰にも通知されません。相手には通知が届かず、カレンダーが見えなくなったことに気づきます。
• GCAL_SHARING=off を設定すると、共有に関する 3 つのツールはすべて削除されます。
• クライアントが MCP エリシテーションに対応している場合、サーバーはカレンダーの削除やクリア、公開、ドメイン全体への公開、誰かへのオーナー権限の付与、ゲストにメールを送る形でのイベントのキャンセル、重なるすべての会議を辞退する不在または集中時間イベントの作成、分割後の新しいシリーズを含む予定の移動、延長、繰り返し回数の増加を行う前に、ユーザー自身に確認を求めます。 Accept を選択した場合にのみ書き込みが実行されます。それ以外は [blocked] になります。確認を求められないクライアントでは質問は表示されません。ただし、GCAL_REQUIRE_PROMPT=true が設定されている場合は、代わりにこれらの書き込みが拒否されます。
• ログにはメソッド、ツール、結果、処理時間、短縮されたカレンダー ID が記録されます。メールアドレス、イベントのタイトル、説明、場所、検索語は記録されません。デバッグログは、どのような場合でもバグ報告に安全に貼り付けられます。

開発

make check は CI で実行されるすべての処理を実行し、make parity は その 2 つのリストが同じであることを検証します。CONTRIBUTING.md を参照してください。

このリポジトリの外部にアクセスするため、CI ではなく手動で実行する処理が 2 つあります。make live は、作成後に削除する一時的なカレンダー上で、ビルド済みバイナリを実際の アカウントに対して実行します。make evals は、インメモリの カレンダーを対象に、これらのツールを使ってモデルが docs/architecture.md §3 の 3 つのタスクを完了できるかを評価し、 ANTHROPIC_API_KEY が必要です。 go run -tags=evals ./scripts/evals -self-check は、キーもモデルも使わずに ハーネスを実行します。

ライセンス

Apache 2.0。LICENSE を参照してください。