cal-auto-python

Python 用自動カレンダー

mcp-name: io.github.danielsousaoliveira/cal-auto-python

GitHub Projects のバックログを Google Calendar と Google Tasks に接続する MCP サーバーです。アシスタントからアクセスし、カレンダーの予定やバックログの一覧を確認したり、空き時間に合わせて1週間分の作業を計画したり、その計画を実際の予定や ToDo に変換したりできます。

左側のバックログボードが右側のスケジュール済みの1週間に変わり、各 Markdown チェックボックスはそれぞれ独立した ToDo として引き継がれます。

変更前	変更後

インストール

$ pip install cal-auto-python

これにより、CLI と MCP サーバーの両方を起動する cal-auto-python コマンドがインストールされます。

1回限りの認証

サーバーがカレンダーの読み取りや書き込みを行う前に、Google アカウントで一度認証します。

$ cal-auto-python authorize

ブラウザーウィンドウが開き、サインインしてカレンダーとタスクへのアクセスを許可するよう求められます。認証後のトークンはディスクに保存されます（下記の設定ディレクトリ内の token.json）。サーバーを初めて起動する前に実行してください。また、認証の有効期限が切れた場合も再度実行してください。詳しくはトラブルシューティングをご覧ください。

認証には Google OAuth クライアントが必要です。

1. Google Cloud Console でプロジェクトを作成（または既存のプロジェクトを使用）し、Google Calendar API と Google Tasks API を有効にします。
2. APIs & Services → Credentials で、種類が Desktop app の OAuth クライアント ID を作成し、生成された JSON をダウンロードします。
3. 設定ディレクトリに credentials.json として保存します。場所や変更方法については設定をご覧ください。

アシスタントに接続する

このサーバーはデフォルトで stdio 経由の MCP 通信を行います。以下のクライアントはこの方式を想定しています。どのクライアントでも、すべての機能を同じように利用できます。

Claude Code

次のコマンドを1つ実行して登録します。

$ claude mcp add auto-calendar \
    -e GITHUB_TOKEN=your_github_token_here \
    -e GITHUB_PROJECT_ID=PVT_xxxxxxxxxx \
    -e CAL_AUTO_TIMEZONE=Europe/Lisbon \
    -- cal-auto-python server

現在のプロジェクトだけでなく、すべてのプロジェクトで利用できるようにするには、-s user を追加します。トークンが ~/.claude.json やプロセス一覧に表示されないようにするには、設定をファイルに記述して、そのファイルを指定してください。Claude Code は起動したディレクトリからサーバーを起動するため、パスは絶対パスで指定する必要があります。

$ claude mcp add auto-calendar -- cal-auto-python server --env-file /absolute/path/to/.env

その後、/mcp にサーバーとそのツールが表示され、プロンプトは /auto-calendar:plan-week と /auto-calendar:whats-scheduled として表示されます。登録状況を確認するには claude mcp list を、登録を解除するには claude mcp remove auto-calendar を使用します。

Claude Desktop

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "auto-calendar": {
      "command": "cal-auto-python",
      "args": ["server"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here",
        "GITHUB_PROJECT_ID": "PVT_xxxxxxxxxx",
        "CAL_AUTO_TIMEZONE": "Europe/Lisbon"
      }
    }
  }
}

Cursor

プロジェクト内の .cursor/mcp.json（またはグローバル設定の ~/.cursor/mcp.json）に追加します。

{
  "mcpServers": {
    "auto-calendar": {
      "command": "cal-auto-python",
      "args": ["server"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here",
        "GITHUB_PROJECT_ID": "PVT_xxxxxxxxxx",
        "CAL_AUTO_TIMEZONE": "Europe/Lisbon"
      }
    }
  }
}

汎用（stdio 対応の MCP クライアント全般）

{
  "command": "cal-auto-python",
  "args": ["server"],
  "env": {
    "GITHUB_TOKEN": "your_github_token_here",
    "GITHUB_PROJECT_ID": "PVT_xxxxxxxxxx",
    "CAL_AUTO_TIMEZONE": "Europe/Lisbon"
  }
}

クライアントを使わずにサーバーの動作を試すには、 MCP Inspector をサーバーに接続します。

$ npx @modelcontextprotocol/inspector cal-auto-python server

ウェブベースのクライアントや、サーバーをあるマシンで実行して別のマシンから接続したい場合、stdio の子プロセスを起動できません。その場合は、代わりに HTTP 経由でサーバーを実行してください。

$ cal-auto-python server --transport http --host 127.0.0.1 --port 8000

HTTP モードは単一ユーザー向けで、ローカルでの使用のみを想定しています。 サーバーはディスクに保存された 1 人分の Google 認証情報を読み込み、ユーザーを個別に管理する機能はありません。また、HTTP エンドポイントに独自の認証機能を追加しません。共有ネットワークや公開ネットワークで公開すると、接続できる全員がそのカレンダーにアクセスできるため、127.0.0.1 またはプライベートで信頼できるネットワークのみにバインドしてください。

前提条件

• GitHub パーソナルアクセストークン：スケジュールの作成元とする Projects V2 ボードへの読み取りアクセス権が必要です。read:project スコープを持つクラシックトークン（ボードがプライベートリポジトリのアイテムを追跡する場合は repo も必要）、または Projects への読み取りアクセス権を付与したファイングレインドトークンを使用してください。GITHUB_TOKEN として設定します。
• ボードの Projects V2 ノード ID（例：PVT_xxxxxxxxxx）。プロジェクトについて GitHub GraphQL API にクエリを送信するか、プロジェクトの URL とProjects API ドキュメントから確認できます。GITHUB_PROJECT_ID として設定します。
• Google OAuth クライアント（デスクトップアプリタイプ）。上記の一度限りの認証の説明をご覧ください。

機能

ツール	引数	説明
status	—	設定されている連携機能と、Google の認証が存在するかどうかを報告します。シークレットは公開されません。
list_calendar_entries	start、end（YYYY-MM-DD、両端を含む）	指定した期間のカレンダーの予定と終日アイテムを一覧表示します。
list_todos	—	設定されている Google Tasks リストの未完了アイテムを一覧表示します。
list_tracker_items	statuses（省略可能なリスト。例：["Backlog", "In Progress"]）	GitHub Projects ボードの作業アイテムを一覧表示します。必要に応じてステータスで絞り込めます。省略するとすべて表示します。
plan_week	items、start_date、end_date、working_day_start、working_day_end、timezone（省略可能）、commitments（省略可能）	指定したアイテムと既存の予定を考慮し、空いている勤務時間の枠に作業を計画します。計算のみを行い、設定済みのアカウントにはアクセスしません。
sync_backlog	start_date、end_date、apply（デフォルトはfalse）	スケジュール可能なバックログを取得し、既存のカレンダーの予定に合わせて調整した結果を返します。デフォルトではプレビューを表示します。イベントと To-do を作成するには、apply=trueを指定します。すでにスケジュール済みのアイテムはスキップされます。
create_calendar_entry	summary、start、end、timezone、description（省略可能）、attendees（省略可能）	カレンダーの予定を1件作成します。スケジュール調整や重複排除は行いません。
create_todo	title、note（省略可能）、due（省略可能）	Google Tasks のタスクを1件作成します。重複排除は行いません。

よく使うワークフローをまとめた2つのプロンプトがあり、対応クライアントではワンクリックで開始できる項目として表示されます（たとえば、Claude Code と Claude Desktop のスラッシュコマンド）。どちらも省略可能なstart_dateとend_date（YYYY-MM-DD）を受け取り、デフォルトでは次の7日間を対象とします。

プロンプト	内容
plan-week	バックログと既存の予定を読み込み、スケジュールをプレビューした後、書き込みを行う前に確認を待ちます。
whats-scheduled	日ごとのカレンダーの予定と未完了の To-do を要約し、予定が詰まりすぎている日や、カレンダーに時間が割り当てられていない To-do を知らせます。

CLI からも同じスケジュール調整ロジックを直接利用できます。

$ cal-auto-python sync --start 2026-08-17 --end 2026-08-21 --apply

syncはデフォルトでプレビューを表示します。イベントとタスクを作成するには--applyを指定します。また、--start／--end（YYYY-MM-DD）または--working-day-start／--working-day-end（HH:MM）を指定すると、デフォルトの期間（今日とその翌々日まで）と勤務時間を上書きできます。

設定

以下の変数はすべて省略可能ですが、GITHUB_TOKEN、GITHUB_PROJECT_ID、およびデフォルト値がなく設定必須の CAL_AUTO_TIMEZONE は例外です。

設定はプロセスの環境から読み込まれます。MCP クライアントでは、サーバー設定の env ブロックにこれらを指定します。CLI を使う場合は、変数をエクスポートするか、.env.example を .env にコピーして、コマンドで明示的に指定します。

$ cal-auto-python sync --env-file .env

--env-file は指定されたファイルを読み込みます（このオプションを渡した場合に限ります。作業ディレクトリから自動的に読み込まれることはありません）。適用されるのは CAL_AUTO_* と GITHUB_* のキーのみです。それ以外のキーは警告とともに無視されます。環境にすでに設定されている変数は、ファイルの値より優先されます。

変数	デフォルト	目的
GITHUB_TOKEN	(必須)	Projects ボードの照会に使用する GitHub トークンです。
GITHUB_PROJECT_ID	(必須)	読み取るボードの GitHub Projects V2 ノード ID です。
CAL_AUTO_TIMEZONE	(必須)	イベントのスケジュール設定に使用する IANA タイムゾーン名です。例：Europe/Lisbon。
CAL_AUTO_CONFIG_DIR	%APPDATA%\cal-auto-python（Windows）、$XDG_CONFIG_HOME/cal-auto-python、または ~/.config/cal-auto-python	credentials.json と token.json を格納するディレクトリです。
CAL_AUTO_WORKING_DAY_START	09:00	始業時刻です。形式は HH:MM です。
CAL_AUTO_WORKING_DAY_END	17:00	終業時刻です。形式は HH:MM です。
CAL_AUTO_CALENDAR_ID	primary	イベントのスケジュール先となる Google Calendar ID です。
CAL_AUTO_TASK_LIST_ID	@default	タスクの作成先となる Google Tasks リスト ID です。
CAL_AUTO_ATTENDEES	(なし)	スケジュールされたイベントに招待するメールアドレスをカンマ区切りで指定します。
CAL_AUTO_SCHEDULABLE_STATUSES	Backlog	スケジュール対象とする GitHub Project のステータス名をカンマ区切りで指定します。ボードのステータス名と完全に一致する必要があります。
CAL_AUTO_COUNT_ALL_DAY_EVENTS	false	終日イベントを空き時間枠に含めるかどうかを指定します。

トラブルシューティング

認証エラー／「Google アカウントが認証されていません」 cal-auto-python authorize を再度実行してください。自動更新できなかった期限切れの認証も解消できます（長期間使用されなかった場合や、Google アカウントの設定からアクセス権が取り消された場合、Google は更新トークンを無効化します）。サーバーはこの状態を明示的に報告するため、エラーが通知されずに処理が失敗することはありません。

イベントが予期しない時刻に表示される CAL_AUTO_TIMEZONE を確認してください。有効な IANA 名（例：Europe/Lisbon。CET や UTC オフセットではありません）であり、実際に作業するタイムゾーンと一致している必要があります。スケジューラーはシステムのタイムゾーンではなく、この値を使ってイベントを配置します。

ボードにカードがあるのに、list_tracker_items または sync_backlog が何も返さない CAL_AUTO_SCHEDULABLE_STATUSES（デフォルトは Backlog）は、ボードのステータス列名と大文字・小文字も含めて完全に一致する必要があります。ボードを開いてステータス名をそのままコピーするか、list_tracker_items に statuses 引数を明示的に渡して、ボードが実際に返すステータスを確認してください。

ロードマップ

[x] github からプロジェクトデータを取得する
[x] google calendar にイベントとタスクを追加する
[x] 優先度に基づいてスケジュールを設定する
[x] イベントとタスクの重複を修正する
[x] ハードコードされたエントリーポイントを実際の CLI に置き換える
[x] MCP サーバーとして実行する（cal-auto-python server）
[x] イベントの分配を最適化する
[x] 計画が変更されたときにイベントを更新または移動する

コントリビュート

別のタスクトラッカーやカレンダーバックエンドを追加しますか？レイヤーと手順については docs/ARCHITECTURE.md を、テスト、リンター、型チェッカーの実行方法については CONTRIBUTING.md をご覧ください。

参考資料

Google Calendar API
Github Projects API