Timebook

io.github.squidcodePublished by GitHub account squidcodev0.6.0Updated Oct 24, 2026

Track time on usetimebook.com - start/stop timers, log entries, list projects/clients.

VerifiedStreamable HTTPWeb executableProductivity & Workflow

Overview

AI-generated overview

Timebook MCP server that lets an assistant track time: start and stop timers, log entries, and list projects and clients in a Timebook account.

What you can do
Check the authenticated user and list projects and clients in scope, read-only, to resolve names before acting on them. Start and stop the running timer on a project. Log manual time entries by duration or by start and end times. List recent entries with project and date filters. Edit fields on an entry or delete an entry, subject to token ownership and invoiced-entry locks.
When to use it
Useful when you want an AI assistant to record or adjust working time in Timebook conversationally, for example starting a timer for a task, logging hours against a project, or correcting and removing recent entries.
Requirements
Either the hosted Streamable-HTTP endpoint with OAuth 2.0, or the local npm package run with Node.js 18.17 or later over stdio. Local use needs a one-time login in a terminal that saves an API token to a config file. Optional TIMEBOOK_API_URL and TIMEBOOK_WEB_URL override the API and web hosts.
Before you install
The assistant can write to your time records: it can start and stop timers, log, edit and delete entries. A token can only modify entries it created itself, and invoiced entries are locked. The saved API token is a credential stored in a local config file; revoke it from Timebook settings if needed. Tool inputs and outputs pass through the MCP host's model context.

Installation

In SourceWeft

  1. Open Timebook in the dashboard and add it to a workspace.
  2. Connect the required credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.squidcode%2Ftimebook/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config. The client completes OAuth sign-in on first connect.

{
  "mcpServers": {
    "timebook": {
      "type": "http",
      "url": "https://usetimebook.com/mcp"
    }
  }
}

README

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.

[npm] [license] [timebook-cli MCP server]

Install

bash
# one-offnpx @squidcode/timebook login
# globallynpm install -g @squidcode/timebooktimebook --help

Requires Node.js 18.17+.

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.

bash
timebook login

The token is stored at:

  • macOS: ~/Library/Preferences/timebook/config.json
  • Linux: ~/.config/timebook/config.json
  • Windows: %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

bash
timebook whoamitimebook projects                         # list projectstimebook clients                          # list clients
timebook start -p "Acme website" -d "Wireframes"timebook status                           # show running timertimebook stop
# manual entriestimebook 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:00timebook entries edit ENTRY_ID -d ""                    # clear descriptiontimebook entries delete ENTRY_ID

Duration 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

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

Or, if installed globally:

json
{  "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-server
  • Resource 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

ToolWhat it does
whoamiCurrent authenticated user (read-only)
list_projectsAll projects in scope (read-only)
list_clientsAll clients in scope (read-only)
get_active_timerThe running timer, or null (read-only)
start_timerStart a timer on a project
stop_timerStop the running timer
log_timeLog a manual entry (duration OR startTime+endTime)
list_entriesRecent entries (default 50, max 500), project + date filters
update_entryEdit one or more fields on an entry (description, duration, startTime, endTime, project, rate). Token must own the entry.
delete_entryDelete 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_entries then update_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 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.
  • Telemetry: none. Neither the CLI nor the MCP server reports usage, errors, or analytics anywhere.
  • 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.
  • 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):

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

You 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:

bash
timebook login --debug

Develop

bash
git clone https://github.com/squidcode/timebook-clicd timebook-clinpm installnpm run dev -- --help        # tsx-powered hot-loopnpm run build                # emits dist/npm run lint && npm run typecheck && npm run test

Pre-commit hooks (ESLint + Prettier via lint-staged) are wired up by husky on npm install.

Release

prepublishOnly runs lint + typecheck + tests + build, then:

bash
npm publish --access public

License

MIT © Squidcode LLC. See LICENSE.

Source: README.md at commit d2416f1

Tools

0
This server asks you to sign in, so SourceWeft could not read its tools without an account and has not indexed them. What a connected account sees can depend on that account and its permissions.

Version history

1
  1. v0.6.0LatestSep 16, 2026

Score

85% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts