内容
<!-- mcp-name: io.github.squidcode/timebook -->
# 时间簿命令行客户端
命令行客户端和 **MCP 服务器**，用于 [时间簿](https://usetimebook.com) - 记录时间、管理计时器，并通过 [模型上下文协议](https://modelcontextprotocol.io) 将您的 Timebook 账户暴露给 AI 代理（Claude、Codex、Cursor 等）。
[](https://www.npmjs.com/package/@squidcode/timebook)
[](./LICENSE)
[](https://glama.ai/mcp/servers/squidcode/timebook-cli)
## 安装
```bash
# 一次性
npx @squidcode/timebook login
# 全局安装
npm install -g @squidcode/timebook
timebook --help
```
需要 Node.js **18.17+**。
## 身份验证
`timebook login` 会打开您的浏览器，您登录 Timebook（或使用现有的会话）并选择一个范围（该令牌可以访问哪些客户端/项目）。浏览器会将令牌返回给一个短暂的回环 HTTP 监听器，然后 CLI 将其写入一个配置文件中，权限为 `0600`。
```bash
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`。
## 作为命令行客户端使用
```bash
timebook whoami
timebook projects # 列出项目
timebook clients # 列出客户
timebook start -p "Acme 网站" -d "线框图"
timebook status # 显示正在运行的计时器
timebook stop
# 手动条目
timebook log -p "Acme 网站" -t 1h30m -d "代码审查"
timebook log -p PROJ_ID --start 2026-05-04T09:00 --end 2026-05-04T10:30
timebook entries --project "Acme 网站" -n 10
# 编辑/删除（任意组合字段；未设置的字段保持不变）
timebook entries edit ENTRY_ID -t 2h -d "代码审查 + 测试"
timebook entries edit ENTRY_ID --start 2026-05-04T09:00 --end 2026-05-04T11:00
timebook entries edit ENTRY_ID -d "" # 清除描述
timebook entries delete ENTRY_ID
```
接受的持续时间格式：`1h`、`45m`、`1h30m`、`1.5h`、`1:30` 或纯数字（解释为分钟 - 例如 `90` → 1h 30m）。
**编辑/删除授权：** API 令牌只能修改它自己创建的条目。JWT 会话（网页 UI）和管理员令牌绕过此规则。已计费的条目对所有人锁定。通过 API 返回 403 和友好消息，尝试被拒绝 - 从网页 UI 或创建它的令牌修复条目。
## 作为 MCP 服务器使用
同一个二进制文件在 `timebook mcp` 调用时通过 stdio 讲话 MCP。将其放入任何 MCP 感知主机（Claude Code、Claude Desktop、Codex、Cursor 等）：
### Claude Code / Claude Desktop
```json
{
"mcpServers": {
"timebook": {
"command": "npx",
"args": ["-y", "@squidcode/timebook", "mcp"]
}
}
}
```
或，如果全局安装：
```json
{
"mcpServers": {
"timebook": {
"command": "timebook",
"args": ["mcp"]
}
}
}
```
MCP 服务器重用 `timebook login` 保存的令牌 - 在启动代理之前在终端中运行 `timebook login` 一次。
### 作为远程 MCP 使用（Claude.ai 网页）
时间簿还在 **`https://usetimebook.com/mcp`** 以托管的 Streamable-HTTP MCP 服务器运行，具有完整的 OAuth 2.0（动态客户端注册 + PKCE + 刷新令牌轮换）。无需 CLI 安装 - Claude.ai 通过标准知名端点发现它：
- 身份验证服务器元数据：`https://usetimebook.com/.well-known/oauth-authorization-server`
- 资源元数据：`https://usetimebook.com/.well-known/oauth-protected-resource/mcp`
从 Claude.ai → 设置 → 连接器 → 添加 → 粘贴 `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` | 编辑条目的一个或多个字段（描述、持续时间、开始时间、结束时间、项目、费率）。令牌必须拥有该条目。 |
| `delete_entry` | 删除条目。令牌必须拥有它。已计费的条目已锁定。 |
### 使用提示尝试
一旦 MCP 服务器连接，请用纯英语询问模型：
- _"在我的 Acme 网站项目上启动一个计时器，用于登陆页面线框图。"_
- _"我上周在 Recycler 项目上记录了多少时间？"_
- _"以软件开发费率记录 1 小时 30 分钟到 ChatNexus，从今天早上 9 点开始，描述为 '身份验证重构的代码审查'。"_
- _"我当前正在处理什么？"_ - 调用 `get_active_timer`。
- _"停止我的计时器。"_
- _"我的 Recycler 上的最后一个条目应该是 2 小时，而不是 1h45m。修复它。"_ - 调用 `list_entries` 然后 `update_entry`。
- _"删除我刚刚错误创建的条目。"_ - 调用 `delete_entry`。如果条目由不同的令牌（网页 UI，另一个代理）创建，将返回 403 - 对模型说出来，以免一直重试。
模型选择正确的工具，如果需要消除歧义，则首先询问 `list_projects`，并通过 `start_timer` / `log_time` / `stop_timer` 写入。
## 隐私
时间簿 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/网页主机（适用于自托管 Timebook 或本地开发）：
```bash
TIMEBOOK_API_URL=https://api.example.com \
TIMEBOOK_WEB_URL=https://example.com \
timebook login
```
您还可以将 `--api-url` 和 `--web-url` 传递给 `timebook login` 一次；后续命令将重用保存的值。
如果 `timebook login` 出现 `State mismatch` 错误，或者您想查看哪些请求到达回环回调，请运行 `--debug`:
```bash
timebook login --debug
```
## 开发
```bash
git clone https://github.com/squidcode/timebook-cli
cd timebook-cli
npm install
npm run dev -- --help # tsx 支持的热循环
npm run build # 生成 dist/
npm run lint && npm run typecheck && npm run test
```
预提交钩子（ESLint + Prettier via `lint-staged`）由 `husky` 在 `npm install` 时连接。
## 发布
`prepublishOnly` 运行 lint + typecheck + 测试 + 构建，然后：
```bash
npm publish --access public
```
## 许可证
MIT © Squidcode LLC. 查看 [LICENSE](./LICENSE)。
