CLI & MCP

Track time from your terminal — or hand it to your AI agent

WorkingClock ships a command-line client and a Model Context Protocol server. Script your hours in CI, or let Codex and Claude Code start timers and pull reports for you — all through the same API your account already uses.

Start tracking free Talk to us

zsh

$ workingclock start --project "Website redesign"
Started at 09:14:02.
$ workingclock status
▶ Website redesign · Homepage copy  00:42:11
$ workingclock stop
Stopped at 10:31:48. Logged 1h 17m.

The CLI and the MCP server are published on npm as workingclock and workingclock-mcp, both at 1.0. They cover timers, projects, entries, and reports; they follow semantic versioning, so a command only changes in a way that breaks your scripts in a new major version.

Install the CLI

Install it, log in once, and you are tracking time from the terminal. The CLI is a plain npm package — Node 20 or newer is the only requirement.

Install the package
npm install -g workingclock puts a workingclock binary on your PATH.
Log in once
workingclock login opens your browser, you sign in the way you always do — password, Google, Microsoft, Apple, MFA — and the session lands in your OS keychain.
Start your first timer
workingclock start --project "Website redesign" starts the same timer you see in the web, desktop, and mobile apps.

On a CI runner — or any machine you cannot log in from interactively — skip the login and pass an API token instead. Tokens are covered below.

zsh

$ npm install -g workingclock
$ workingclock login
Sign-in code: 7MKM-HQ8J
Opening your browser…
Logged in. Active org: Acme Studio.
$ workingclock start --project "Website redesign"
Started at 09:14:02.

A CLI built for scripts and CI

Start and stop the same timer you see on web, mobile, and desktop. There is no client-side state — every command goes through the REST API, and every read command takes --json so it drops straight into a pipeline.

One running timer, everywhere
A timer you start in the terminal shows up live in the web, desktop, and mobile apps — and the other way around.
--json on every read
status, log, report, and the catalog commands emit clean JSON for jq, a dashboard, or a nightly cron.
Names, not UUIDs
--project "Website redesign" resolves against the API, so you never look up an id by hand.

zsh

$ workingclock login
Logged in. Active org: Acme Studio.
$ workingclock log --today --json
[
  {
    "project": "Website redesign",
    "task": "Homepage copy",
    "seconds": 4620,
    "billable": true
  }
]
$ workingclock report summary --from 2026-07-13 --to 2026-07-18
Total       18h 20m
Billable    18h 20m
Website redesign   12h 30m
API migration       5h 50m

Get an API token

Interactive login covers your own machine. Everything else — a CI job, a cron, the MCP server — authenticates with an API token you create in the web app, under Settings → API tokens.

It is shown once, right after you create it: we store only a hash, so copy it there and then.
It inherits the permissions of the person who created it — an agent using it never sees more than you can.
It does not expire unless you give it an expiry date, and you can revoke it at any time.
Put it in WORKINGCLOCK_API_TOKEN. Both the CLI and the MCP server read it from the environment.

WORKINGCLOCK_ORGANIZATION_ID picks the organization to work in. You'll find the id in the app under Settings → API tokens, just above the token list — or run workingclock org list --json.

Create a token in the app

zsh

$ workingclock org list --json
[
  {
    "organizationId": "3f1c9a7e-…",
    "organization": { "name": "Acme Studio", "slug": "acme-studio" },
    "role": "OWNER"
  }
]
$ export WORKINGCLOCK_API_TOKEN="wc_…"
$ export WORKINGCLOCK_ORGANIZATION_ID="3f1c9a7e-…"
$ workingclock log --today --json

mcp config

{
  "mcpServers": {
    "workingclock": {
      "command": "npx",
      "args": ["-y", "workingclock-mcp"],
      "env": {
        "WORKINGCLOCK_API_TOKEN": "wc_…",
        "WORKINGCLOCK_ORGANIZATION_ID": "3f1c9a7e-…"
      }
    }
  }
}

An MCP server your AI agent can drive

The Model Context Protocol server exposes WorkingClock as tools an assistant can call. It is headless and stdio-based, authenticates from environment variables, and forwards your own token — so the agent only ever sees what you can see.

Set it up

Create an API token in the web app, under Settings → API tokens. Your organization id is on the same screen — copy both.
Paste the config block into your MCP host — Claude Code, Codex, or anything else that speaks MCP.
Restart the host and ask it to start a timer. npx fetches the server on first run, so there is nothing to clone or build.

Prefer to let your assistant do it?

Most MCP hosts can edit their own configuration. Paste this prompt, swapping in your token and organization id, and let the assistant wire it up for you.

Add an MCP server named "workingclock" to my configuration: command: npx args: ["-y", "workingclock-mcp"] env: WORKINGCLOCK_API_TOKEN=wc_… WORKINGCLOCK_ORGANIZATION_ID=3f1c9a7e-… Then reconnect and list the workingclock tools to confirm it works.

Tools the agent gets

Read — list projects, tasks, entries, and summary reports
Write — start, stop, create, update, and delete time entries
Every call is tenant- and permission-scoped by the backend; the server holds no elevated access

Works with Codex, Claude Code, and any MCP host

Point your assistant at the WorkingClock MCP server and track time the way you already work — in the same chat where you are writing code.

Things you can just ask

“Start a timer on Website redesign, task Homepage copy, and mark it billable.”

Started at 09:14. Running on Website redesign · Homepage copy, billable.

“How many billable hours did I log for Acme Inc. this week?”

18h 20m billable across 3 projects — Website redesign leads at 12h 30m.

“Stop whatever is running and show me today’s total.”

Stopped at 12:02. Today: 4h 52m across 5 entries.

Bring your hours into your workflow

Create a free account, then wire up the CLI or the MCP server against your own token.

Start tracking free