when-free

when-free

空いている時間を聞かれたときに、カレンダーを読み取って、すぐに貼り付けられる回答を返します。

• メッセージを貼り付けると、空き時間がわかります。「来週の火曜日か水曜日、午前10時から午後4時」と読み取り、その日時だけを対象に回答します。
• Google、Outlook、iCloud のカレンダー、または任意の .ics ファイルで使えます。複数のカレンダーを同時に利用できます。
• **プライベートです。**コンピューター上で動作し、アカウントや API キーは不要で、カレンダーを変更することもありません。
• **AI ツールからも使えます。**Claude、Cursor、その他の MCP クライアント、Open WebUI、n8n、Shortcuts、スクリプトに対応しています。
• **ほかのデバイスでも使えます。**スマートフォン、タブレット、スマートウォッチ、Home Assistant（Alexa、Google Home、Siri からも利用できます）、macOS、Linux、Windows のメニューバーやステータスバーに対応しています。

目次

1 分で試す · カレンダーを追加する · 日常的な使い方 · メッセージを読み取る · ほかのツールから使う · ほかのデバイス · プライバシー · 設定 · 予定ありと見なされる条件 · 制限 · 問題が発生した場合 · 掲載先

1 分で試す

uv があれば、事前のインストールは不要です。

uvx when-free demo

インストールして使い続ける場合（Python 3.11 以降が必要です）：

uv tool install when-free          # or: pipx install when-free
whenfree demo

Claude Desktop をお使いですか？以下をすべて省略できます。ワンクリック拡張機能をインストールしてください。

whenfree demo は来週の架空のカレンダーを作成し、それを使って採用担当者のメッセージに回答します。データは一切読み取らず、何も保存しません。

  > Hi! Thanks for applying. Could you share a few times on Tuesday, Wednesday or Thursday next week,
  > between 10am and 4pm? The interview takes about an hour.

  Free between 10:00 and 16:00 (Europe/London), slots of 60+ minutes, 15-minute buffer around events:
  - Tue 13 Oct: 11:45–12:45, 14:15–16:00
  - Wed 14 Oct: 12:15–14:15
  - Thu 15 Oct: 13:15–14:45

カレンダーを追加する

1. カレンダーの非公開アドレスをコピーします。 .ics で終わるリンクです。

   カレンダー	確認場所
   Google Calendar	設定 → 左側でカレンダーをクリック → カレンダーの統合 → iCal 形式の非公開アドレス
   Outlook	設定 → カレンダー → 共有カレンダー → カレンダーを公開 → ICS リンク
   iCloud	カレンダー → カレンダーの横にある共有アイコン → 公開カレンダー（webcal:// リンクでも問題ありません）
   その他	任意の .ics リンク、またはエクスポートした .ics ファイル

2. whenfree add を実行して貼り付けます。 貼り付け中にアドレスは表示されません。まず確認が行われ、使える場合にのみ保存されます。

   $ whenfree add
   Paste the address and press Enter (it is not shown):
   Added 'personal': 412 events, 9 block time in the next 14 days.
   Saved in /Users/you/.config/when-free/config.toml, readable only by you. Now run: whenfree
   

3. whenfree を実行します。 直近の営業日の空き時間が表示されます。

Mac では、pbpaste | whenfree add を実行すると、クリップボードからアドレスを直接渡せます。

アドレスは秘密にしてください。 パスワードのようなもので、持っている人は誰でもそのカレンダーを読めます。whenfree add 以外には渡さないでください。チャットやシェルコマンド、リポジトリに渡さないようにしてください。漏えいした場合は、カレンダーの設定でリセットしてください。

whenfree add --name work                 # a second calendar: asks for its address
whenfree add ~/calendars/family.ics      # an exported file instead of an address
whenfree check                           # can every calendar be read?

日常的な使い方

標準出力に出力されるのは時間帯の行だけです。補足情報は標準エラー出力に送られるため、| pbcopy を使うと、返信に貼り付ける内容だけをコピーできます。

メッセージを読み取る

--message は通常のテキストから曜日と時間を見つけます。次のような表現を理解します。

• さまざまな一般的な書き方の日付： Thu 1 Oct · Thursday the 1st of October · Monday, October 5th · 5 October · 2026-10-05 · Wednesday 30th
• 時間： between 10:00am and 4:00pm · 10:00–16:00 · 9-5pm · 2 to 4 pm
• 日付がない場合の語句（今日が10月1日木曜日の場合）：

日付をどう読み取ったかは必ず表示されるので、メッセージと照らし合わせて確認できます。推測を避けるため、いくつかのルールがあります。

• 明示された日付が優先されます。「Wednesday 30th, Thursday 1st」の上に「Next week:」という見出しがあっても、丸々1週間追加されることはありません。
• 「Good morning」は挨拶であり、時刻ではありません。
• すでに過ぎた曜日は除外され、必ず明記されます。「Wednesday 30th」は、最も近い30日の水曜日を意味するため、先週のメッセージなら先週の日付として読み取られます。
• 日付のない語句は今日を基準にします。「tomorrow」と書かれた古いメッセージの場合は、--days を使って日付を自分で指定してください。

when-free がメールボックスに接続することはありません。メッセージを貼り付けるか、パイプで渡すか、ファイルに保存してください。

[extract]
command = ["ollama", "run", "llama3.2"]          # the prompt is sent on standard input
# command = ["my-cli", "ask", "{prompt}"]        # or placed where {prompt} is

他のツールから使う

どの方法でも同じ結果が得られ、読み取り専用で、明示的に指定しない限りイベントのタイトルは含まれません。

Claude Code プラグイン

このプラグインには MCP サーバーと、Claude に使うタイミングを指示するスキルが含まれています。空き状況について尋ねたとき、いつ会えるかを尋ねるメッセージを貼り付けたとき、または時間を提案する前に使用します。

/plugin marketplace add YauhenBichel/when-free
/plugin install when-free@when-free

次に、まだ追加していない場合は、カレンダーを一度追加してください：uvx when-free add。

MCP：Claude、Cursor などのアシスタント

claude mcp add when-free -- uvx when-free mcp          # Claude Code

Cursor やその他の MCP クライアントでは、サーバーリストにこれを追加します。初回は uvx が when-free を取得するため、インストールは不要です。

{
  "mcpServers": {
    "when-free": { "command": "uvx", "args": ["when-free", "mcp"] }
  }
}

uv tool install でインストールした場合は、代わりに "command": "whenfree", "args": ["mcp"] を使用してください。MCP レジストリでは io.github.YauhenBichel/when-free として、mcprushおよびM8ven Trust Indexにも掲載されています。

あとは、*「採用担当者からのメッセージです。この時間帯のうち、どれなら空いていますか？」*と尋ねるだけです。アシスタントは free_slots を呼び出し、実際のカレンダーに基づいて回答します。

ツールが処理を完了できない場合、アシスタントは推測せず、読み取れるエラー（「カレンダー 'work' を読み取れませんでした」）を受け取ります。

HTTP：Open WebUI、n8n、Shortcuts、スクリプト

whenfree serve                    # http://127.0.0.1:8765, only reachable from this computer

curl -H "Authorization: Bearer $(cat ~/.config/when-free/token)" \
  'http://127.0.0.1:8765/free_slots?days=next%20week&hours=afternoon'

• JSON ボディを指定して POST /free_slots を送信するか、クエリ文字列を指定して GET を送信します。/check_calendars も同様です。
• 応答は {"ok": true, "text": "...", "data": {...}} または、ステータスコード 400 の {"ok": false, "error": "..."} です。
• /openapi.json に OpenAPI の説明があります。Open WebUI、n8n、Shortcuts の設定については、レシピを参照してください。
• トークンは初回実行時に作成され、~/.config/when-free/token に保存されます。このファイルを読み取れるのはあなただけです。または、WHENFREE_TOKEN で独自のトークンを設定できます。すべてのツール呼び出しにトークンが必要です。
• このコンピューター以外のホスト宛てのリクエストは拒否されます。Web ページから呼び出せるのは、許可したオリジンからのみです：whenfree serve --allow-origin http://localhost:3000。--host 0.0.0.0 を指定するとネットワークからアクセスできるようになります。トークンだけで保護されるため、信頼できるネットワークでのみ使用してください。

関数呼び出しハーネス

whenfree schema                    # the tool definitions: name, description, inputSchema
whenfree schema --format openai    # the same, as {"type": "function", "function": {...}}
whenfree call free_slots --args '{"days": "next week", "hours": "10:00-16:00"}'

whenfree call は {"ok": true, "text": "...", "data": {...}} または、終了コード 1 の {"ok": false, "error": "..."} を出力します。引数は標準入力から渡すこともできます。

Python

from whenfree import api

result = api.find_free(api.Query(days="next week", hours="10:00-16:00", min_minutes=45))
for day in result["days"]:
    print(day["label"], day["free"])          # for example: Mon 12 Oct [['10:00', '11:45'], ['13:15', '16:00']]

find_free は、json.dumps ですぐに使える通常の辞書とリストを返し、安全に表示できるメッセージを含む api.Problem を送出します。カレンダーのテキストを取得する代わりに自分で渡すには、reader= を指定します。

ほかのデバイスで使う

$ whenfree now
Busy until 15:30 · next free 15:45–17:00

デバイスに表示されるのは、空いているかどうかと空き時間だけで、イベントのタイトルは表示されません。各スマートフォンには個別のトークンがあり、取り消すことができます。読み取れないカレンダーは「不明」と表示され、「空き」とは表示されません。

プライバシー

• コンピューター上で動作します。 カレンダーフィードを取得するだけで、それ以外の情報は取得しません。カレンダーへの書き込みやメッセージの送信は一切行いません。
• カレンダーのアドレスは秘密のままです。 表示されることはなく、貼り付けている間も画面に表示されません。また、あなたしか読み取れないファイルに保存されます。エラーにはカレンダーのアドレスではなく、カレンダー名（「personal」など）が表示されます。
• アシスタントに表示されるのは空き時間であり、予定ではありません。 アシスタントが include_busy を指定して要求しない限り、予定のタイトルは含まれません。また、そのオプションの説明では、タイトルが非公開であることをモデルに伝えます。予定の追加、変更、削除ができるツールはありません。また、カレンダーのアドレスを受け取るツールもありません。アドレスは、あなたから whenfree add にのみ渡されます。

設定

カレンダー以外はすべて任意です。設定は ~/.config/when-free/config.toml に保存され、コマンドラインフラグはファイルの設定より優先されます。

予定ありとして扱われるもの

空き時間を差し引いた後の時間枠が min_minutes より短い場合、その時間枠は提示されません。今日については、過去の時刻ではなく、次の15分単位の時刻から開始します。

制限事項

• 読み取り専用です。予約はしません。 カレンダーへの書き込みやメッセージの送信は行いません。
• フィードの更新状況に依存します。 Google がシークレットアドレスを更新するまでには時間がかかるため、1 分前に追加された予定が表示されない場合があります。whenfree --busy を実行すると、読み取った内容を確認できます。
• すべてのカレンダーを読み取れる場合のみ表示します。 1 つでも読み取れないカレンダーがあると、予定のない時間に見えてしまうため、空き時間枠は表示されません。
• 繰り返しの予定。 日次、週次、月次（日付指定、または「第 1 月曜日」「最終金曜日」）および年次のルールは、間隔、終了日、回数、スキップした日付、変更された回を含めて展開します。まれなルール（BYSETPOS、週番号）には対応していません。その場合は最初の日付を予定ありとして扱い、その旨を注記します。
• タイムゾーン は予定から取得します。タイムゾーンデータベースが認識しないタイムゾーン名（Outlook のエクスポートの一部など）は、お使いのタイムゾーンで読み取ります。

動作しない場合

掲載先

• 公式の MCP registry（io.github.YauhenBichel/when-free として掲載）
• PyPI（when-free として掲載）
• MCP サーバーをインデックス化している Glama、MCP Servers Live、MCP Changefeed

どこかで利用したり、紹介記事を書いたりした場合は、Issue を作成してください。ここに掲載します。

開発

uv run --with pytest pytest -q        # a few seconds; no network

テストでは、tests/data/sample.ics の小規模なカレンダーと固定クロック（WHENFREE_NOW）を使用します。コードはコンポーネントごとにまとめられています。

tests/test_structure.py は、使用が許可されていないコンポーネントを別のコンポーネントがインポートすると失敗するため、ドメイン層をフロントエンドから独立させています。

CONTRIBUTING.md を参照してください。

ライセンス

Apache-2.0。