Timebook MCP server

<!-- mcp-name: io.github.squidcode/timebook -->

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 --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.

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

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

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

{
  "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-server
• Resource metadata: https://usetimebook.com/.well-known/oauth-protected-resource/mcp

Shortened. The full README is on GitHub.