Google Calendar MCP Server (Python)

calendar-mcp

LLM クライアントに Google カレンダーへの読み書きアクセスを提供する MCP サーバーです。単一プロセスとして動作し、デフォルトでは stdio、オプションでストリーミング可能な HTTP を使用します。また、構造化出力を備えた 23 個のツールを公開しています。カレンダーとイベントの一覧表示と検索、イベントの作成、更新、移動、RSVP、削除、空き時間の照会、忙しさの分析、繰り返しイベントの投影、共通の空き枠の検出と予約などが可能です。さらに、就業時間を把握するスケジューリング機能を備えており、集中時間の検出と予約、複数のアカウントにまたがるダブルブッキングの同時検出、会議により適した時間帯の提案、1 週間が実際にどこで使われたかの監査などが行えます。認証には Google OAuth 2.0（デスクトップアプリフロー）を使用します。トークンはアカウントごとにローカルにキャッシュされ、自動的に更新されます。

カレンダータスクの一連の流れ

オフラインテストに基づく合成例です。実際のカレンダーデータや実際の予約は使用していません。 木曜日の就業時間を 09:00〜17:00 UTC、会議が 11:00〜12:00 に 1 件、 ランチやバッファなし、最小の集中ブロックを 60 分と仮定します。

「2026 年 1 月 1 日に 6 時間の集中時間を見つけてください。まずブロックを表示してください。」

MCP クライアントは次のように呼び出せます。

{
  "tool": "block_focus_time",
  "arguments": {
    "time_min": "2026-01-01T00:00:00Z",
    "time_max": "2026-01-02T00:00:00Z",
    "hours_needed": 6,
    "dry_run": true
  }
}

プレビューでは 09:00〜10:00 と 12:00〜17:00 が選択されます。合計 6 時間で、最後に 選択されたブロックは残りの 1 時間に切り詰められます。どちらのイベントも created: false です。 ユーザーが時間を承認した後、クライアントは dry_run: false を指定して呼び出せます。 イベントを作成する前に空き状況が再度読み取られます。プレビューは枠を予約しません。

設計上の判断: 不明な空き状況は空き時間とはみなしません。 チェック対象のカレンダーが アクセスエラーを返した場合、レスポンスから消えた場合、または busy の間隔が読み取れない場合、 集中時間の検索と予約は何も書き込む前にエラーを返します。同じチェックが共通スケジューリング および再スケジュールの提案・適用も保護します。たとえば [email protected] に対する notFound レスポンスは次のようになります。

Availability is unknown: [email protected]: notFound. No scheduling changes were made.
Restore calendar access or retry the query.

Google の認証情報なしでプレビューと安全性のリグレッションを再現できます （開発用インストールの後）:

pytest -q tests/test_scheduling.py -k 'focus_time_dry_run or focus_refuses_unknown'

このリグレッションは、部分的、欠落、エラーを含む空き状況がプレビューモードと予約モードの 両方で create_event を決して呼び出さないことを検証します。空の busy リストが正常に返された 場合は、依然として本当に空き時間であることを意味します。空き状況のチェックと書き込みは別々の Google API 呼び出しであるため、その間に別のクライアントが競合するイベントを予約する可能性が あります。

クイックスタート

1. Google OAuth 認証情報を作成します。Google Cloud コンソールで Google Calendar API を有効化し、種類が Desktop app の OAuth クライアント ID を作成します。クライアント ID とシークレットをコピーします。（詳細は Google Cloud のセットアップを参照してください。）

2. 環境変数に設定します。または、実行するディレクトリの .env ファイルに設定します（example.env を参照）:

GOOGLE_CLIENT_ID='...'
GOOGLE_CLIENT_SECRET='...'

3. 一度サインインし、その後サーバーをクライアントに追加します:

uvx calendar-mcp-server auth

これによりブラウザーが開き、トークンが設定ディレクトリに保存されます（アカウントを参照）。既に .gcp-saved-tokens.json がある場合、または TOKEN_FILE_PATH を設定している場合は、代わりにそのファイルが使用されます。calendar-mcp check で確認できます。Google アカウントをさらに追加するには calendar-mcp auth --account work を使用します。その後、サーバーは非対話的に動作します。CALENDAR_MCP_ALLOW_BROWSER_AUTH=1 を設定しない限り、サーバーが自らブラウザーを開くことはありません。

PyPI での配布名は calendar-mcp-server です。同一のコンソールスクリプト calendar-mcp と calendar-mcp-server の 2 つがインストールされるため、uvx calendar-mcp-server とローカルの calendar-mcp は同じコマンドです。

クライアント設定

Claude Code

claude mcp add calendar \
  --env GOOGLE_CLIENT_ID=... \
  --env GOOGLE_CLIENT_SECRET=... \
  -- uvx calendar-mcp-server

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "calendar": {
      "command": "uvx",
      "args": ["calendar-mcp-server"],
      "env": {
        "GOOGLE_CLIENT_ID": "...",
        "GOOGLE_CLIENT_SECRET": "...",
        "TOKEN_FILE_PATH": "/absolute/path/to/.gcp-saved-tokens.json"
      }
    }
  }
}

Cursor — .cursor/mcp.json（プロジェクト）または ~/.cursor/mcp.json（グローバル）: 上記と同じ mcpServers ブロックを使用します。

その他のクライアントで標準の mcpServers JSON を扱える場合は、同じエントリを使用できます。トークンはデフォルトで OS の設定ディレクトリに保存され、クライアントが選択する作業ディレクトリに依存しないため、TOKEN_FILE_PATH は現在では任意です。ただし設定する場合は絶対パスにしてください。

リモート / HTTP モード

calendar-mcp --transport http --host 127.0.0.1 --port 8000

MCP エンドポイントは http://127.0.0.1:8000/mcp になります（パスは --path で変更できます）。

HTTP トランスポートにはまだ認証レイヤーがありません。 エンドポイントに到達できる人は誰でも、保存されたトークンが属するカレンダーに完全にアクセスできます。ループバックにバインドするか、認証を行う信頼できるリバースプロキシの背後にのみ公開するか、tailnet などのプライベートネットワーク上でのみ公開してください。パブリックインターフェースに置かないでください。

ツール

読み取り専用ツールは何も変更しません。「書き込み」ツールはイベントを作成または変更します。 delete_event だけがデータを破壊します。

カレンダーとイベント

ツール		説明
list_calendars	読み取り	ユーザーが閲覧できるカレンダーを、ID とタイムゾーンとともに一覧表示します。
find_events	読み取り	カレンダー内のイベントを検索し、繰り返しシリーズを個別のインスタンスに展開します。
check_attendee_status	読み取り	招待を承諾した人、辞退した人、まだ回答していない人を報告します。
query_free_busy	読み取り	1 つ以上のカレンダーのビジー時間帯を、イベントの詳細なしで表示します。
analyze_busyness	読み取り	指定期間における日ごとのイベント数と予定の合計時間。
project_recurring_events	読み取り	繰り返しルールから将来の発生を計算します。
create_calendar	書き込み	新しいセカンダリカレンダーを作成します。
create_event	書き込み	開始/終了時刻を明示し、任意で参加者を指定してイベントを作成します。
quick_add_event	書き込み	Google が解析する平易な英語のフレーズからイベントを作成します。
update_event	書き込み	イベントのフィールドを変更します。省略されたフィールドはそのまま残ります。
move_event	書き込み	イベントの日程を変更したり、別のカレンダーに移動したりします。
add_attendee	書き込み	既存のイベントに 1 人以上を招待します。
respond_to_event	書き込み	自分の RSVP（accepted/declined/tentative/needsAction）を設定します。
schedule_mutual	書き込み	全員が空いている最初の時間枠を見つけて、予約します。
delete_event	破壊	イベントを完全に削除します。対応している場合は、elicitation を通じてクライアントに確認を求めます。

スケジューリングブレイン — 保存された設定（勤務時間、昼休み、バッファー、最小フォーカスブロック）を読み取ります。

ツール		説明
find_focus_time	読み取り	ある時間帯の中で集中作業に使える中断のないブロックを、長い順に表示します。
detect_conflicts	読み取り	ダブルブッキングと、間隔が詰まりすぎた切り替えを、サインインしているすべてのアカウントにわたって一度に検出します。
time_audit	読み取り	時間がどこに使われたか: 会議時間を、規模、ドメイン、繰り返し、人物ごとに表示します。
suggest_reschedule	書き込み (オプトイン)	既存の会議について、より良い時間帯を順位付けして提示します。apply: true でない限り提案のみです。
block_focus_time	書き込み	最適な空きブロックをフォーカス時間として予約します。プレビューには dry_run: true。

ローカル設定 — Google の呼び出しはなく、account 引数もありません。

ツール		説明
list_accounts	読み取り	サインイン済みのアカウントと、どれがデフォルトかを表示します。
get_preferences	読み取り	勤務時間、昼休み、バッファー、最小フォーカスブロック、フォーカスカレンダー。
set_preferences	書き込み	これらの設定を更新して保存します。ローカルファイルのみです。

すべてのカレンダーツールは、省略可能な末尾の account 引数を取ります（detect_conflicts は複数を一度に確認することが目的であるため、リストである accounts を取ります）。すべての時刻は ISO 8601 文字列です — タイムゾーンを持たないタイムスタンプは、対象カレンダー自身のタイムゾーンとして解釈されます。

スケジューリングの頭脳

5つのスケジューリングツールは1つの考え方を共有しています。あなたのカレンダーは、あなたの空き時間とは同じではないということです。これらはあなたの勤務時間から出発し、昼食を差し引き、すでに予定が入っている分を差し引き、さらに会議の前後に確保したいバッファーを差し引いたうえで、残った時間について推論します。

これらを活用するプロンプトの例:

• 「来週の6時間の集中時間を見つけてブロックして。まずその時間帯を見せて。」
• 「今週、仕事用と個人用のカレンダーの間でダブルブッキングしているものはある?」
• 「木曜日がびっしり詰まっている。デザインレビューのためにより良い時間を提案して。」
• 「先月、自分の時間はどこへ消えた? 誰と過ごしている?」
• 「金曜日までに90分のディープワークのブロックが必要。空いている?」

find_focus_time は存在する時間を報告し、block_focus_time はイベントを作成してそれを守ります(予定あり、リマインダーなし、誰にも通知なし)。そして最後のブロックを調整して、午後まるごとではなく、あなたが指定したちょうどの時間数を予約します。detect_conflicts は、本当の重複と、単にバッファーを侵害するぎりぎりの切り替えを区別し、あなたが辞退したイベント、空きとしてマークされたイベント、(デフォルトでは)終日予定を無視します。suggest_reschedule は会議の所要時間を維持し、候補スロットを参加者の衝突が最も少ない順にランク付けし、そのイベントの現在の曜日を優先します。そして apply: true を渡さない限り、何も移動しません。

時間の監査

time_audit は「私の1週間のうちどれだけが会議か?」という問いに、day または week でグループ化して一度に答えます:

2026-08-01 .. 2026-09-01, Europe/Berlin, grouped by week
  Meetings:         41.5 h across 63 meetings
  Working hours:    152.0 h available (lunch removed)
  In working hours: 38.0 h -> 25% of the week
  Busiest week:     2026-W34, 14.0 h
  Heaviest day:     2026-08-20, 6.5 h
  By size:          1:1 18.0 h | small 15.5 h | large 8.0 h
  By recurrence:    recurring 26.0 h | one-off 15.5 h
  Top people:       [email protected] 9.0 h | [email protected] 7.5 h

辞退した会議、空きとしてマークされたイベント、終日予定はデフォルトでは除外されます。include_declined と include_all_day でそれらを含めることができます。

安全性

• delete_event は唯一の破壊的なツールです。 クライアントが対応している場合は、MCP の elicitation を通じて確認を求めてから実行し、対応していない場合は通常どおり続行します。
• block_focus_time は dry_run を受け付けます。 dry_run: true を付けて実行すると、何かが書き込まれる前に、予約される正確なブロックを確認できます。対象カレンダーは常に空き時間チェックに含まれます。
• スケジューリングは、空き状況が不明な場合にはフェイルクローズします。 フォーカス時間の検索/予約、両方の相互スケジューリングの経路、再スケジュールの提案/適用は、チェック対象のすべてのカレンダーについて読み取り可能な空き状況を必要とします。エラーは予約後の警告ではなく、書き込み前に返されます。スケジューリングの前にアクセスを復元するか、再試行してください。デフォルトのフォーカスカレンダーの検出も、不完全なページ分割されたカレンダー一覧を拒否します。その場合は、calendar_ids / check_calendar_ids で明示的に完全な一覧を指定してください。
• suggest_reschedule はデフォルトでは何も移動しません。 apply は false であり、ユーザーが時間に同意した後に明示的に設定する必要があります。
• 書き込みを行うその他すべては追加的です — イベントの作成や編集など — そして update_event は省略したフィールドをそのままにします。
• list_accounts、get_preferences、set_preferences は Google に一切アクセスしません。 これらは設定ディレクトリ内のローカルファイルを読み書きします。

アカウント

複数の Google アカウントでサインインし、呼び出しごとにそれらを選択できます。

calendar-mcp auth                    # the default account
calendar-mcp auth --account work     # a second, named account
calendar-mcp accounts                # list them, with token paths and sign-in state

すべてのカレンダーツールは、これらのいずれかの名前を指定する省略可能な account 引数を受け取ります (「明日の仕事のカレンダーの予定は?」)。省略すると、サーバーは デフォルトを使用します。設定されていれば CALENDAR_MCP_DEFAULT_ACCOUNT、そうでなければ default という名前のアカウント、それもなければサインインしている唯一のアカウントです。list_accounts は CLI が出力するのと同じリストを返すので、モデル自身が名前を発見できます。

アカウント名は [A-Za-z0-9][A-Za-z0-9_-]{0,63} に一致する必要があります。

保存場所。 トークンと設定は OS のユーザー設定ディレクトリに保存されます — Windows では %LOCALAPPDATA%\calendar-mcp、Linux では ~/.config/calendar-mcp、 macOS では ~/Library/Application Support/calendar-mcp — で、アカウントごとに 1 つの トークンファイルが accounts/ の下に置かれます。ディレクトリ全体は CALENDAR_MCP_CONFIG_DIR で上書きできます。

後方互換性。 TOKEN_FILE_PATH は引き続き機能し、現在はデフォルト アカウントのトークンを意味します。これが設定されている場合、または作業ディレクトリに .gcp-saved-tokens.json が存在する場合、そのファイルが default アカウントに使用され、何も 移動しません。名前付きアカウントは常に設定ディレクトリに保存されます。

設定

サーバーはあなたが 1 週間をどのように過ごしたいかを記憶しているので、スケジューリング ツールが推測する必要はありません。get_preferences で読み取り、set_preferences で変更します (「8 時に開始し、会議の間に 15 分ほしい」)。設定はグローバルです — それらはあなたを表し、1 つのアカウントを表すものではありません — そして 設定ディレクトリに preferences.json として保存されます。

フィールド	デフォルト	意味
timezone	未設定	勤務時間を表現する IANA ゾーン。例: Europe/Berlin。
working_hours	月〜金 09:00〜17:00	曜日ごと (mon…sun) の、["HH:MM", "HH:MM"] 形式の時間帯のリスト。
buffer_minutes	0	時刻を提案する際に会議の前後に空ける間隔。
min_focus_block_minutes	60	使用可能な集中時間として数えられる最短の空き時間。
lunch	未設定	勤務時間から確保する毎日の休憩。
focus_calendar_id	primary	集中時間ブロックを予約するカレンダー。

{
  "timezone": "Europe/Berlin",
  "working_hours": {
    "mon": [["09:00", "12:00"], ["13:00", "18:00"]],
    "tue": [["09:00", "17:00"]],
    "wed": [["09:00", "17:00"]],
    "thu": [["09:00", "17:00"]],
    "fri": [["09:00", "15:00"]],
    "sat": [],
    "sun": []
  },
  "buffer_minutes": 15,
  "min_focus_block_minutes": 90,
  "lunch": ["12:30", "13:15"],
  "focus_calendar_id": "primary"
}

set_preferences はマージします。渡した引数のみが変更され、マージされた 結果は書き込まれる前に検証されるため、拒否された変更は保存済み ファイルをそのままにします。唯一の例外は working_hours で、これはスケジュール全体の 置き換えです — ディクショナリに含めなかった曜日は非稼働日になります。 昼休みを削除するには clear_lunch: true を渡します。

構成

変数	デフォルト	目的
GOOGLE_CLIENT_ID	—	OAuth クライアント ID (必須)。
GOOGLE_CLIENT_SECRET	—	OAuth クライアントシークレット (必須)。
TOKEN_FILE_PATH	.gcp-saved-tokens.json	デフォルトアカウントの OAuth トークンをキャッシュする場所。
CALENDAR_MCP_CONFIG_DIR	OS のユーザー設定ディレクトリ	アカウントごとのトークン (accounts/) と preferences.json を保持するディレクトリ。
CALENDAR_MCP_DEFAULT_ACCOUNT	default	ツールの account 引数が省略されたときに使用されるアカウント。
CALENDAR_SCOPES	https://www.googleapis.com/auth/calendar	要求するスコープ。読み取り専用にするには .../auth/calendar.readonly を使用します。
OAUTH_CALLBACK_PORT	8080	calendar-mcp auth 中の OAuth コールバック用のローカルポート。
CALENDAR_MCP_ALLOW_BROWSER_AUTH	未設定	トークンが存在しないときにサーバー自身がブラウザーを開けるようにするには 1 を設定します。デフォルトではオフなので、stdio サーバーがハングすることはありません。
CALENDAR_MCP_LOG_FILE	未設定	stderr ログをこのファイルにもミラーリングします。
CALENDAR_MCP_LOG_LEVEL	INFO	DEBUG/INFO/WARNING/ERROR/CRITICAL。--log-level を上書きします。
HOST	127.0.0.1	HTTP モードでの --host のデフォルト。
PORT	8000	HTTP モードでの --port のデフォルト。

作業ディレクトリ内の .env ファイルは起動時に読み込まれます。ログが stdout に出力されることはありません — stdout は stdio モードにおける MCP プロトコルのチャネルです。

コマンド

calendar-mcp [--transport {stdio,http}] [--host H] [--port P] [--path /mcp] [--log-level L]
calendar-mcp serve ...     # explicit form of the default
calendar-mcp auth [--account NAME] [--no-browser]
calendar-mcp accounts      # list known accounts; exit 1 if none is signed in
calendar-mcp check [--account NAME]   # token status + calendar list; exit 1 if no valid token
calendar-mcp --version

python -m calendar_mcp も同じ引数を受け取ります。

Google Cloud のセットアップ

1. プロジェクトを作成または選択し、Google Calendar API を有効化します。
2. API とサービス → 認証情報 → 認証情報を作成 → OAuth クライアント ID → アプリケーションの種類: デスクトップアプリ。 クライアント ID とシークレットをコピーします。保存しておく JSON のダウンロードはありません。
3. デスクトップアプリのクライアントには**「承認済みのリダイレクト URI」フィールドがありません** — Google はこのクライアント種別に対して任意のポートの http://localhost を許可しており、OAUTH_CALLBACK_PORT 上のローカルコールバックはこれを使用します。ここで設定するものはありません。
4. OAuth 同意画面で: ユーザーの種類を外部にし、アプリ名と連絡先メールアドレスを入力し、https://www.googleapis.com/auth/calendar スコープを追加し、ご自身の Google アカウントをテストユーザーとして追加します。この最後の手順がないと、サインインが拒否されます。

開発

git clone https://github.com/deciduus/calendar-mcp
cd calendar-mcp
uv venv
uv pip install -e ".[dev]"
pytest

構成: calendar_mcp/server.py（MCPServer、共有ヘルパー、認証情報プロバイダー）、tools/（ツール領域ごとに 1 モジュール — ツール関数そのもの）、calendar_actions.py（Google API 呼び出し）、analysis.py、timeutil.py（純粋なインターバル計算）、accounts.py（マルチアカウントのトークンパス）、preferences.py（保存されたスケジュール）、models.py（pydantic の入力/出力モデル）、auth.py（OAuth）、cli.py（calendar-mcp コマンド）。scripts/smoke_stdio.py は実際の stdio サーバーを起動し、ハンドシェイクとツール一覧を確認します。

1.0 からのアップグレード

何も壊れません。元の 15 個のツールはすべて名前と既存のパラメータを維持しており、それぞれにオプションの末尾パラメータ account が追加されただけです。既存の TOKEN_FILE_PATH は引き続き機能し、デフォルトアカウントのトークンを指すようになります。スケジューリングの安全性: 利用できない、省略された、または不正な形式の空き時間データは、フォーカス検索、プレビュー、相互スケジューリング、リスケジュールがエラーを返す原因になります。不完全な空き状況で自動スケジューリングの変更が行われることはありません。

新機能: マルチアカウント、保存されたスケジューリング設定、および 8 個の新しいツール（find_focus_time、block_focus_time、detect_conflicts、suggest_reschedule、time_audit、list_accounts、get_preferences、set_preferences）。

0.x からのアップグレード

• パッケージ名とコマンド名が変更されました。 ディストリビューションは calendar-mcp-server になり、calendar-mcp（および同一の calendar-mcp-server エイリアス）をインストールします。クライアントの指定を python /path/to/run_server.py ではなく uvx calendar-mcp-server に変更してください。
• run_server.py は引き続き機能します — 現在は CLI の薄いシムになっています — が、非推奨であり、将来のリリースで削除されます。
• FastAPI/uvicorn の HTTP API はなくなりました。 REST エンドポイントも /health も、独立した stdio ブリッジプロセスもありません。サーバーは MCP SDK 上の単一プロセスです。HTTP が必要な場合は、/mcp の MCP ストリーミング HTTP になりました。
• 認証は暗黙的に行われなくなりました。 calendar-mcp auth を一度実行してください。CALENDAR_MCP_ALLOW_BROWSER_AUTH=1 でない限り、サーバーはブラウザーを開きません。
• ツール名は変更されていないため、既存のプロンプトは引き続き機能します。結果はテキストに詰め込まれた JSON ではなく、構造化出力になりました。
• 3 個の新しいツール: move_event、respond_to_event、project_recurring_events（最後のものは以前は内部ロジックとしてのみ存在していました）。
• 削除された環境変数: RELOAD、MCP_API_HOST。HOST/PORT は MCP HTTP トランスポートに適用されるようになりました。

ライセンス

このプロジェクトは、オープンソースの協業と持続可能な開発の両方を支援するためにデュアルライセンスとなっています:

1. GNU Affero General Public License v3.0 (AGPL-3.0):

   • このソフトウェアは、AGPLv3 ライセンスの条項の下で自由に使用、変更、配布できます。
   • 主な条件には、派生作品(ネットワーク経由で使用される改変版を含む)も AGPLv3 の下でライセンスされ、そのソースコードを公開しなければならないことが含まれます。
   • このライセンスは、AGPLv3 への準拠が可能なオープンソースプロジェクトや内部利用に適しています。
   • 全文については LICENSE ファイルを参照してください。

2. 商用ライセンス:

   • AGPLv3 の条項がお客様の特定のユースケースに適さない場合(例: AGPLv3 のソース共有要件に準拠せずに、このソフトウェアをプロプライエタリなクローズドソースの商用製品やサービスに統合する場合)、別途商用ライセンスをご利用いただけます。
   • 商用ライセンスのオプションに関するお問い合わせは [email protected] までご連絡ください。

このソフトウェアを使用、変更、または配布することにより、お客様は AGPLv3 または別途交渉された商用ライセンスのいずれかの条項に拘束されることに同意するものとします。

mcp-name: io.github.deciduus/calendar-mcp