Timebook

Timebook CLI

Timebook 用のコマンドラインクライアントおよび MCP サーバーです。時間を記録し、タイマーを管理して、Model Context Protocol を介して Timebook アカウントを AI エージェント（Claude、Codex、Cursor、…）に公開できます。

インストール

# one-off
npx @squidcode/timebook login

# globally
npm install -g @squidcode/timebook
timebook --help

Node.js 18.17+ が必要です。

認証

timebook login を実行するとブラウザーが開き、Timebook にログインするか既存のセッションを使用して、スコープ（このトークンがアクセスできるクライアント／プロジェクト）を選択します。ブラウザーから短時間だけ稼働するループバック HTTP リスナーにトークンが渡され、CLI はそれを 0600 のアクセス許可を設定した構成ファイルに書き込みます。

timebook login

トークンは次の場所に保存されます。

• macOS：~/Library/Preferences/timebook/config.json
• Linux：~/.config/timebook/config.json
• Windows：%APPDATA%\timebook\Config\config.json

ログイン後、トークンがマシンの外部に送信されることはありません。サーバー側でトークンを取り消すには、https://usetimebook.com/settings/api-tokens にアクセスしてください。

CLI として使う

timebook whoami
timebook projects                         # list projects
timebook clients                          # list clients

timebook start -p "Acme website" -d "Wireframes"
timebook status                           # show running timer
timebook stop

# manual entries
timebook log -p "Acme website" -t 1h30m -d "Code review"
timebook log -p PROJ_ID --start 2026-05-04T09:00 --end 2026-05-04T10:30

timebook entries --project "Acme website" -n 10

# edit / delete (any combination of fields; unset ones stay as-is)
timebook entries edit ENTRY_ID -t 2h -d "code review + tests"
timebook entries edit ENTRY_ID --start 2026-05-04T09:00 --end 2026-05-04T11:00
timebook entries edit ENTRY_ID -d ""                    # clear description
timebook entries delete ENTRY_ID

使用できる期間形式は、1h、45m、1h30m、1.5h、1:30、または数字のみです（分として解釈されます。例：90 → 1h 30m）。

編集／削除の認可： API トークンで変更できるのは、そのトークン自身が作成したエントリのみです。JWT セッション（Web UI）と管理者トークンではこのルールは適用されません。請求済みのエントリは API 経由では誰も変更できません。操作が拒否されると、わかりやすいメッセージとともに 403 が返されます。その場合は Web UI、またはエントリを作成したトークンを使って修正してください。

MCP サーバーとして使う

同じバイナリは timebook mcp を指定して実行すると、stdio 経由で MCP を使用できます。MCP 対応ホスト（Claude Code、Claude Desktop、Codex、Cursor、…）に設定してください。

Claude Code / Claude Desktop

{
  "mcpServers": {
    "timebook": {
      "command": "npx",
      "args": ["-y", "@squidcode/timebook", "mcp"]
    }
  }
}

または、グローバルにインストールしている場合：

{
  "mcpServers": {
    "timebook": {
      "command": "timebook",
      "args": ["mcp"]
    }
  }
}

MCP サーバーは timebook login で保存したトークンを再利用します。エージェントを起動する前に、ターミナルで一度 timebook login を実行してください。

リモート MCP として使う（Claude.ai Web）

Timebook は、OAuth 2.0（動的クライアント登録 + PKCE + リフレッシュトークンのローテーション）に完全対応した、ホスト型 Streamable-HTTP MCP サーバー（https://usetimebook.com/mcp）としても稼働します。CLI のインストールは不要です。Claude.ai は標準の well-known エンドポイントを介してサーバーを検出します。

• 認証サーバーのメタデータ：https://usetimebook.com/.well-known/oauth-authorization-server
• リソースのメタデータ：https://usetimebook.com/.well-known/oauth-protected-resource/mcp

Claude.ai から［Settings］→［Connectors］→［Add］を開き、https://usetimebook.com/mcp を貼り付けて接続します。Timebook の同意ページに一度リダイレクトされた後、Claude は以下に記載されているものと同じすべてのツールを使用できます。権限は、他の正式なコネクターと同様の OAuth 形式です。

HTTP エンドポイントでは、OAuth よりもトークンの貼り付けを優先するクライアント（サーバー間での利用を含む）向けに、Authorization: Bearer tbk_*（既存の API トークン）も受け付けます。

モデルに公開されるツール

ツール	機能
whoami	現在認証されているユーザー（読み取り専用）
list_projects	対象範囲内のすべてのプロジェクト（読み取り専用）
list_clients	対象範囲内のすべてのクライアント（読み取り専用）
get_active_timer	実行中のタイマー、または null（読み取り専用）
start_timer	プロジェクトのタイマーを開始します
stop_timer	実行中のタイマーを停止します
log_time	手動で記録します（duration または startTime+endTime）
list_entries	最近の記録（デフォルトは50件、最大500件）、プロジェクトと日付のフィルター
update_entry	記録の1つ以上のフィールドを編集します（description、duration、startTime、endTime、project、rate）。トークンはその記録の所有者である必要があります。
delete_entry	記録を削除します。トークンはその記録の所有者である必要があります。請求済みの記録はロックされています。

プロンプトで試す

MCP サーバーを接続したら、モデルに自然な英語で尋ねます。

• 「ランディングページのワイヤーフレーム作成のために、Acme website プロジェクトのタイマーを開始して。」
• 「先週、Recycler プロジェクトにどれくらい時間を記録した？」
• 「今朝9時から、Software Development の料金で、ChatNexus に1時間30分を記録して。説明は 'code review of the auth refactor' にして。」
• 「今、何に取り組んでいる？」 — get_active_timer を呼び出します。
• 「タイマーを停止して。」
• 「Recycler の直近の記録は1時間45分ではなく2時間にするべきだった。修正して。」 — list_entries の後に update_entry を呼び出します。
• 「さっき誤って作成した記録を削除して。」 — delete_entry を呼び出します。別のトークン（ウェブ UI、別のエージェント）で作成された記録の場合は403エラーになります。モデルにその旨を伝え、何度も再試行しないようにしてください。

モデルは適切なツールを選び、名前の特定が必要な場合は最初に list_projects を呼び出し、start_timer / log_time / stop_timer を使って記録します。

プライバシー

Timebook CLI はお使いのマシン上で実行され、Timebook アカウントとのみ通信します。

• 認証：timebook login は、Timebook の OAuth 形式の同意画面を通じて個人用 API トークンを発行します。トークンはローカルに 0600 の権限で保存されます（macOS では ~/Library/Preferences/timebook/config.json、Linux では ~/.config/timebook/config.json、Windows では %APPDATA%\timebook\Config\config.json）。送信 API 呼び出し時に https://usetimebook.com（または独自に設定した URL）以外へ送信されることはありません。
• テレメトリー：ありません。CLI も MCP サーバーも、使用状況、エラー、分析データを外部に送信しません。
• MCP ホストのデータ：Claude / Cursor などの内部で timebook mcp を使用する場合、モデルが何を見るかは MCP ホスト（Timebook ではありません）が制御します。ツールの入力と出力は、ホストの通常のモデルコンテキスト処理パイプラインを通じて送られます。
• アクセスの取り消し：https://usetimebook.com/settings/api-tokens にアクセスすれば、いつでもトークンを取り消せます。

Timebook の製品レベルのプライバシーポリシーについては、https://usetimebook.com/privacy をご覧ください。

設定

API／Web のホストを上書きします（セルフホスト版の Timebook やローカル開発に便利です）。

TIMEBOOK_API_URL=https://api.example.com \
TIMEBOOK_WEB_URL=https://example.com \
timebook login

timebook login に --api-url と --web-url を一度渡すこともできます。以降のコマンドでは、保存された値が再利用されます。

timebook login で State mismatch エラーが発生する場合、またはループバックコールバックに届くリクエストを正確に確認したい場合は、--debug を付けて実行します。

timebook login --debug

開発

git clone https://github.com/squidcode/timebook-cli
cd timebook-cli
npm install
npm run dev -- --help        # tsx-powered hot-loop
npm run build                # emits dist/
npm run lint && npm run typecheck && npm run test

npm install の実行時に、husky によってプリコミットフック（lint-staged 経由の ESLint + Prettier）が設定されます。

リリース

prepublishOnly で lint + typecheck + tests + build が実行されます。その後、次を実行します。

npm publish --access public

ライセンス

MIT © Squidcode LLC。LICENSE を参照してください。