Timebook

Timebook CLI

Timebook 的命令行客户端和 MCP 服务 — 用于追踪时间、管理计时器，并通过模型上下文协议向 AI Agent（Claude、Codex、Cursor 等）开放你的 Timebook 账户。

安装

# 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 保存的令牌 — 在启动 Agent 之前，先在终端中运行一次 timebook login。

将其用作远程 MCP（Claude.ai 网页版）

Timebook 还以托管的 Streamable-HTTP MCP 服务形式运行，地址为 https://usetimebook.com/mcp，支持完整的 OAuth 2.0（动态客户端注册 + PKCE + 刷新令牌轮换）。无需安装 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 端点还接受 Authorization: Bearer tbk_*（你现有的 API 令牌），供偏好粘贴令牌而非使用 OAuth 的客户端使用 — 包括服务器到服务器的场景。

向模型公开的工具

工具	功能
whoami	当前已认证的用户（只读）
list_projects	范围内的所有项目（只读）
list_clients	范围内的所有客户（只读）
get_active_timer	正在运行的计时器，或 null（只读）
start_timer	在某个项目上启动计时器
stop_timer	停止正在运行的计时器
log_time	记录手动条目（duration 或 startTime+endTime）
list_entries	最近的条目（默认 50 条，最多 500 条），可按项目和日期筛选
update_entry	编辑条目中的一个或多个字段（description、duration、startTime、endTime、project、rate）。令牌必须属于该条目的所有者。
delete_entry	删除条目。令牌必须属于该条目的所有者。已开票的条目已锁定。

试着用提示词操作

连接 MCP 服务后，可以用日常语言向模型提问：

• “在我的 Acme 网站项目上，为落地页线框图启动计时器。”
• “上周我在 Recycler 项目上记录了多少时间？”
• “今天早上 9 点开始，为 ChatNexus 记录 1 小时 30 分钟，费率为 Software Development，并填写描述‘审查 auth 重构的代码’。”
• “我现在在做什么？” — 调用 get_active_timer。
• “停止我的计时器。”
• “我在 Recycler 上的上一条记录应该是 2 小时，不是 1 小时 45 分钟。请修正。” — 调用 list_entries，然后调用 update_entry。
• “删除我刚才误创建的条目。” — 调用 delete_entry。如果该条目由其他令牌（网页 UI、其他 Agent）创建，将返回 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（或你设置的覆盖地址）外，令牌绝不会传送到其他地方。
• 遥测：无。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。