{
  "markdown": "<!-- mcp-name: io.github.squidcode/timebook -->\n\n# Timebook CLI\n\nCommand-line client and **MCP server** for [Timebook](https://usetimebook.com) — track time, manage timers, and expose your Timebook account to AI agents (Claude, Codex, Cursor, …) over the [Model Context Protocol](https://modelcontextprotocol.io).\n\n[![npm](https://img.shields.io/npm/v/%40squidcode%2Ftimebook.svg)](https://www.npmjs.com/package/@squidcode/timebook)\n[![license](https://img.shields.io/npm/l/%40squidcode%2Ftimebook.svg)](./LICENSE)\n[![timebook-cli MCP server](https://glama.ai/mcp/servers/squidcode/timebook-cli/badges/score.svg)](https://glama.ai/mcp/servers/squidcode/timebook-cli)\n\n## Install\n\n```bash\n# one-off\nnpx @squidcode/timebook login\n\n# globally\nnpm install -g @squidcode/timebook\ntimebook --help\n```\n\nRequires Node.js **18.17+**.\n\n## Authenticate\n\n`timebook login` opens your browser, you log into Timebook (or use an existing session) and pick a scope (which clients/projects this token can touch). The browser delivers the token back to a short-lived loopback HTTP listener, which the CLI then writes to a config file with `0600` permissions.\n\n```bash\ntimebook login\n```\n\nThe token is stored at:\n\n- macOS: `~/Library/Preferences/timebook/config.json`\n- Linux: `~/.config/timebook/config.json`\n- Windows: `%APPDATA%\\timebook\\Config\\config.json`\n\nThe token never leaves your machine after login. To revoke it server-side, visit `https://usetimebook.com/settings/api-tokens`.\n\n## Use it as a CLI\n\n```bash\ntimebook whoami\ntimebook projects                         # list projects\ntimebook clients                          # list clients\n\ntimebook start -p \"Acme website\" -d \"Wireframes\"\ntimebook status                           # show running timer\ntimebook stop\n\n# manual entries\ntimebook log -p \"Acme website\" -t 1h30m -d \"Code review\"\ntimebook log -p PROJ_ID --start 2026-05-04T09:00 --end 2026-05-04T10:30\n\ntimebook entries --project \"Acme website\" -n 10\n\n# edit / delete (any combination of fields; unset ones stay as-is)\ntimebook entries edit ENTRY_ID -t 2h -d \"code review + tests\"\ntimebook entries edit ENTRY_ID --start 2026-05-04T09:00 --end 2026-05-04T11:00\ntimebook entries edit ENTRY_ID -d \"\"                    # clear description\ntimebook entries delete ENTRY_ID\n```\n\nDuration formats accepted: `1h`, `45m`, `1h30m`, `1.5h`, `1:30`, or a bare number (interpreted as minutes — e.g. `90` → 1h 30m).\n\n**Edit / delete authorization:** an API token can only modify entries it created itself. JWT sessions (the web UI) and admin tokens bypass this rule. Invoiced entries are locked for everyone via the API. A 403 with a friendly message is returned on a denied attempt — fix the entry from the web UI or with the token that created it.\n\n## Use it as an MCP server\n\nThe same binary speaks MCP over stdio when invoked with `timebook mcp`. Drop it into any MCP-aware host (Claude Code, Claude Desktop, Codex, Cursor, …):\n\n### Claude Code / Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"timebook\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@squidcode/timebook\", \"mcp\"]\n    }\n  }\n}\n```\n\nOr, if installed globally:\n\n```json\n{\n  \"mcpServers\": {\n    \"timebook\": {\n      \"command\": \"timebook\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nThe MCP server reuses the token saved by `timebook login` — run `timebook login` once in a terminal before starting the agent.\n\n### Use it as a remote MCP (Claude.ai web)\n\nTimebook also runs as a hosted Streamable-HTTP MCP server at **`https://usetimebook.com/mcp`** with full OAuth 2.0 (Dynamic Client Registration + PKCE + refresh-token rotation). No CLI install required — Claude.ai discovers it via the standard well-known endpoints:\n\n- Auth-server metadata: `https://usetimebook.com/.well-known/oauth-authorization-server`\n- Resource metadata: `https://usetimebook.com/.well-known/oauth-protected-resource/mcp`\n\nConnect from Claude.ai → Settings → Connectors → Add → paste `https://usetimebook.com/mcp`. You'll be redirected to Timebook's consent page once, then Claude can use all the same tools listed below. Same OAuth-style permissions you'd see for any first-class connector.\n\nThe HTTP endpoint also accepts `Authorization: Bearer tbk_*` (your existing API token) for any client that prefers token-paste over OAuth — including server-to-server use.\n\n### Tools exposed to the model\n\n| Tool               | What it does                                                                                                              |\n| ------------------ | ------------------------------------------------------------------------------------------------------------------------- |\n| `whoami`           | Current authenticated user (read-only)                                                                                    |\n| `list_projects`    | All projects in scope (read-only)                                                                                         |\n| `list_clients`     | All clients in scope (read-only)                                                                                          |\n| `get_active_timer` | The running timer, or `null` (read-only)                                                                                  |\n| `start_timer`      | Start a timer on a project                                                                                                |\n| `stop_timer`       | Stop the running timer                                                                                                    |\n| `log_time`         | Log a manual entry (`duration` OR `startTime`+`endTime`)                                                                  |\n| `list_entries`     | Recent entries (default 50, max 500), project + date filters                                                              |\n| `update_entry`     | Edit one or more fields on an entry (description, duration, startTime, endTime, project, rate). Token must own the entry. |\n| `delete_entry`     | Delete an entry. Token must own it. Invoiced entries are locked.                                                          |\n\n### Try it with prompts\n\nOnce the MCP server is connected, ask the model in plain English:\n\n- _\"Start a timer on my Acme website project for landing-page wireframes.\"_\n- _\"How much time did I log on the Recycler project last week?\"_\n- _\"Log 1 hour 30 minutes against ChatNexus from 9am this morning at the Software Development rate, with description 'code review of the auth refactor'.\"_\n- _\"What am I currently working on?\"_ — invokes `get_active_timer`.\n- _\"Stop my timer.\"_\n- _\"My last entry on Recycler should be 2 hours, not 1h45m. Fix it.\"_ — invokes `list_entries` then `update_entry`.\n- _\"Delete the entry I just made by mistake.\"_ — invokes `delete_entry`. Will 403 if the entry was created by a different token (web UI, another agent) — say so to the model so it doesn't keep retrying.\n\nThe model picks the right tool, asks `list_projects` first if it needs to disambiguate a name, and writes through `start_timer` / `log_time` / `stop_timer`.\n\n## Privacy\n\nTimebook CLI runs on your machine and only talks to your Timebook account.\n\n- **Authentication**: `timebook login` mints a personal API token via Timebook's OAuth-style consent screen. The token is stored locally with `0600` permissions (`~/Library/Preferences/timebook/config.json` on macOS, `~/.config/timebook/config.json` on Linux, `%APPDATA%\\timebook\\Config\\config.json` on Windows). It is never transmitted anywhere except `https://usetimebook.com` (or your override) on outgoing API calls.\n- **Telemetry**: none. Neither the CLI nor the MCP server reports usage, errors, or analytics anywhere.\n- **MCP host data**: when you use `timebook mcp` from inside Claude / Cursor / etc., the MCP host (not Timebook) controls what the model sees. Tool inputs and outputs flow through the host's normal model-context pipeline.\n- **Revoking access**: visit https://usetimebook.com/settings/api-tokens to revoke the token at any time.\n\nFor Timebook's product-level privacy policy, see https://usetimebook.com/privacy.\n\n## Configuration\n\nOverride the API/web hosts (useful for self-hosted Timebook or local dev):\n\n```bash\nTIMEBOOK_API_URL=https://api.example.com \\\nTIMEBOOK_WEB_URL=https://example.com \\\ntimebook login\n```\n\nYou can also pass `--api-url` and `--web-url` to `timebook login` once; subsequent commands re-use the saved values.\n\nIf `timebook login` errors with `State mismatch` or you want to see exactly which requests reach the loopback callback, run with `--debug`:\n\n```bash\ntimebook login --debug\n```\n\n## Develop\n\n```bash\ngit clone https://github.com/squidcode/timebook-cli\ncd timebook-cli\nnpm install\nnpm run dev -- --help        # tsx-powered hot-loop\nnpm run build                # emits dist/\nnpm run lint && npm run typecheck && npm run test\n```\n\nPre-commit hooks (ESLint + Prettier via `lint-staged`) are wired up by `husky` on `npm install`.\n\n## Release\n\n`prepublishOnly` runs lint + typecheck + tests + build, then:\n\n```bash\nnpm publish --access public\n```\n\n## License\n\nMIT © Squidcode LLC. See [LICENSE](./LICENSE).\n",
  "bytes": 9095,
  "sha": "459c8378154f885001051ce86178382c15ecbc4d9bc2ce21cfce21c56e7c3304",
  "repo_slug": "squidcode/timebook-cli",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_squidcode_timebook_13f19b0a/readme"
}