Timebook
OfficialThe Timebook server lets AI agents manage time tracking across users, projects, clients, timers, and time entries.
Account & Discovery
whoami— Retrieve the authenticated user's id, email, and namelist_projects— List all available projects (id, name, client)list_clients— List all available clients
Timer Management
get_active_timer— Check if a timer is running (returns project, description, started_at, or null)start_timer— Start a timer on a project (optional description/rate); automatically stops any existing timerstop_timer— Stop the currently running timer
Time Entry Logging & Management
log_time— Log a manual past entry using a duration (e.g.1h30m) or explicit start/end timestamps, with optional rate and descriptionlist_entries— List recent time entries (default 50, max 500), filterable by project and date rangeupdate_entry— Edit any fields on an existing entry (description, duration, start/end time, project, rate); token must own the entrydelete_entry— Delete a time entry; token must own it and it must not be invoiced
Client & Project Creation
create_client— Create a new client with optional emailcreate_project— Create a new project under a client, with optional description
This server has a remotely hosted endpoint. Open its connector listing for connection details, authentication requirements, and setup instructions:
Timebook CLI
Command-line client and MCP server for Timebook — track time, manage timers, and expose your Timebook account to AI agents (Claude, Codex, Cursor, …) over the Model Context Protocol.
Install
# one-off
npx @squidcode/timebook login
# globally
npm install -g @squidcode/timebook
timebook --helpRequires Node.js 18.17+.
Related MCP server: TimeIQ MCP Server
Authenticate
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.
timebook loginThe token is stored at:
macOS:
~/Library/Preferences/timebook/config.jsonLinux:
~/.config/timebook/config.jsonWindows:
%APPDATA%\timebook\Config\config.json
The token never leaves your machine after login. To revoke it server-side, visit https://usetimebook.com/settings/api-tokens.
Use it as a 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_IDDuration formats accepted: 1h, 45m, 1h30m, 1.5h, 1:30, or a bare number (interpreted as minutes — e.g. 90 → 1h 30m).
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.
Use it as an MCP server
The same binary speaks MCP over stdio when invoked with timebook mcp. Drop it into any MCP-aware host (Claude Code, Claude Desktop, Codex, Cursor, …):
Claude Code / Claude Desktop
{
"mcpServers": {
"timebook": {
"command": "npx",
"args": ["-y", "@squidcode/timebook", "mcp"]
}
}
}Or, if installed globally:
{
"mcpServers": {
"timebook": {
"command": "timebook",
"args": ["mcp"]
}
}
}The MCP server reuses the token saved by timebook login — run timebook login once in a terminal before starting the agent.
Use it as a remote MCP (Claude.ai web)
Timebook 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:
Auth-server metadata:
https://usetimebook.com/.well-known/oauth-authorization-serverResource metadata:
https://usetimebook.com/.well-known/oauth-protected-resource/mcp
Connect 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.
The 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.
Tools exposed to the model
Tool | What it does |
| Current authenticated user (read-only) |
| All projects in scope (read-only) |
| All clients in scope (read-only) |
| The running timer, or |
| Start a timer on a project |
| Stop the running timer |
| Log a manual entry ( |
| Recent entries (default 50, max 500), project + date filters |
| Edit one or more fields on an entry (description, duration, startTime, endTime, project, rate). Token must own the entry. |
| Delete an entry. Token must own it. Invoiced entries are locked. |
Try it with prompts
Once the MCP server is connected, ask the model in plain English:
"Start a timer on my Acme website project for landing-page wireframes."
"How much time did I log on the Recycler project last week?"
"Log 1 hour 30 minutes against ChatNexus from 9am this morning at the Software Development rate, with description 'code review of the auth refactor'."
"What am I currently working on?" — invokes
get_active_timer."Stop my timer."
"My last entry on Recycler should be 2 hours, not 1h45m. Fix it." — invokes
list_entriesthenupdate_entry."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.
The 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.
Privacy
Timebook CLI runs on your machine and only talks to your Timebook account.
Authentication:
timebook loginmints a personal API token via Timebook's OAuth-style consent screen. The token is stored locally with0600permissions (~/Library/Preferences/timebook/config.jsonon macOS,~/.config/timebook/config.jsonon Linux,%APPDATA%\timebook\Config\config.jsonon Windows). It is never transmitted anywhere excepthttps://usetimebook.com(or your override) on outgoing API calls.Telemetry: none. Neither the CLI nor the MCP server reports usage, errors, or analytics anywhere.
MCP host data: when you use
timebook mcpfrom 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.Revoking access: visit https://usetimebook.com/settings/api-tokens to revoke the token at any time.
For Timebook's product-level privacy policy, see https://usetimebook.com/privacy.
Configuration
Override the API/web hosts (useful for self-hosted Timebook or local dev):
TIMEBOOK_API_URL=https://api.example.com \
TIMEBOOK_WEB_URL=https://example.com \
timebook loginYou can also pass --api-url and --web-url to timebook login once; subsequent commands re-use the saved values.
If timebook login errors with State mismatch or you want to see exactly which requests reach the loopback callback, run with --debug:
timebook login --debugDevelop
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 testPre-commit hooks (ESLint + Prettier via lint-staged) are wired up by husky on npm install.
Release
prepublishOnly runs lint + typecheck + tests + build, then:
npm publish --access publicLicense
MIT © Squidcode LLC. See LICENSE.
Available Tools
12 toolscreate_clientAInspect
Create a client (the person/company you bill). Needed before any project or time entry can exist. Typical first step on a fresh account.
Inputs: name (required), email.
create_projectAInspect
Create a project under a client. Time entries are always tracked against a project. Typical second step on a fresh account, after create_client.
Inputs: name (required), client (required), description.
delete_entryADestructiveIdempotentInspect
Delete a time entry. Server enforces: not invoiced, and either this token created it or the caller is an admin / web session.
Inputs: id (required).
get_active_timerARead-onlyIdempotentInspect
Return the currently running timer (project, description, started_at), or null if no timer is running.
Inputs: no named parameters.
list_clientsARead-onlyIdempotentInspect
List all clients available to the current token.
Inputs: no named parameters.
list_entriesARead-onlyIdempotentInspect
List recent time entries, optionally filtered by project and/or date range. Returns at most 50 entries by default; pass a higher limit to see more.
Inputs: project, startDate, endDate, limit.
list_projectsARead-onlyIdempotentInspect
List all projects available to the current token. Returns id, name, and client for each project.
Inputs: no named parameters.
log_timeAInspect
Log a manual (past) time entry. Provide either duration (relative to now), or both startTime and endTime (absolute ISO-8601 timestamps).
Inputs: project (required), description, duration, startTime, +2 more.
start_timerAInspect
Start a timer on a project. Stops any other running timer first — Timebook allows only one active timer at a time.
Inputs: project (required), description, rate.
stop_timerADestructiveIdempotentInspect
Stop the currently running timer. Returns { stopped: false } if no timer was running.
Inputs: no named parameters.
update_entryAInspect
Edit one or more fields on an existing time entry. Any combination is valid; unset fields are left as-is. Server-enforced authorship rule: this token can only edit entries it created itself (sessions and admins bypass).
Inputs: id (required), description, duration, startTime, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool targets a distinct action and resource. For example, create_client is clearly different from start_timer, and list_clients is separate from list_projects. There is no ambiguity between tools.
All tool names follow the imperative verb_noun pattern (e.g., create_client, delete_entry, stop_timer). The only exception is whoami, which is a common standalone command but still consistent with the overall style.
12 tools cover the essential operations for a time tracking service: client and project management, time entry CRUD, timer control, and user info. This is a well-scoped set without excess or deficiency.
The tool set covers the core lifecycle: create and list clients/projects, log and update time entries, and timer operations. Minor gaps like missing update/delete for clients and projects suggest room for improvement, but the core workflow is complete.
Maintenance
Related MCP Connectors
timesheet.io MCP server - manage timers, projects, tasks and reports
Free hosted MCP for invoices, estimates, clients, items and PDFs. OAuth authorization required.
Toggl 2.0 MCP server for tasks, projects, time entries, and workspace operations.
MCP server for MOCO business software: time tracking, projects, budgets, and invoicing via API
Related MCP Servers
- AlicenseBqualityDmaintenanceProduction-grade MCP server for FreshBooks. 25 tools for invoices, clients, expenses, payments, time tracking, projects, estimates, and financial reports. OAuth2 with automatic token refresh.253MIT
- AlicenseCqualityDmaintenanceA production-ready, fully anonymized Model Context Protocol (MCP) server for TimeIQ time tracking. It allows LLM agents to view and manage time entries, projects, clients, reports, invoices, expenses, services, and timesheets via a secure stdio transport.100MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for SolidTime — the open-source time tracking app. Enables start/stop timers, manage time entries, projects, clients, tags, and tasks directly from MCP-compatible clients.3MIT
- FlicenseNot gradedqualityDmaintenanceA scoped MCP server for managing Clockify workspaces, offering read/write tools for clients, projects, tasks, tags, and time entries, with idempotent structure scaffolding and gated deletion.-