clockify-mcp

A local MCP server that lets Claude start, stop, and log Clockify time entries.

It runs as a child process over stdio — no port, nothing listening, no inbound network surface. Claude spawns it, they exchange JSON-RPC over stdin/stdout, and the server talks to api.clockify.me over HTTPS on your behalf.

Claude Code ──JSON-RPC/stdio──► clockify-mcp ──HTTPS + x-api-key──► Clockify

Setup

1. Get a Clockify API key. In the Clockify web app: Preferences → Advanced → API → generate. It's a static personal key — no OAuth, no expiry — and it carries exactly your own permissions.

2. Configure.

cp .env.example .env
# then edit .env and paste the key after CLOCKIFY_API_KEY=

.env is gitignored. The server reads it from its own directory, so the key stays out of ~/.claude.json.

CLOCKIFY_WORKSPACE_ID is optional — the server reads your active workspace from GET /v1/user on first use. Only set it if you belong to several workspaces and want to pin one.

3. Build.

npm install
npm run build

4. Register with Claude Code (user scope makes it available in every project):

claude mcp add clockify --scope user -- node D:/UniqProject/clockify-mcp/dist/index.js
claude mcp list          # expect: clockify: ... ✔ Connected

If you would rather keep the key in Claude's config than in .env, add -e CLOCKIFY_API_KEY=<key> before the --.

Related MCP server: Claude-LMStudio-Bridge

Tools

In practice you don't call these by name — you say "clock 2 hours on the launcher bug" and Claude looks up the project, then logs it.

Times

Every time argument accepts:

Output is shown in your Clockify account's timezone (read from your profile, e.g. Asia/Saigon), so it matches what the Clockify web UI shows. Clockify stores UTC; the conversion happens here.

Gotcha: the list endpoint filters by wall clock, not UTC

GET /v1/workspaces/{ws}/user/{id}/time-entries takes start/end in a format ending in Z, but it does not compare them as UTC — it compares them against wall-clock time in the account's timezone. Verified against the live API on an Asia/Saigon (UTC+7) account:

Entry timestamps in POST/PUT bodies are ordinary UTC — the quirk is filter-only, which makes it easy to miss. toZoneFilter in src/time.ts is the one place that compensates; don't "fix" it back to UTC.

Notes

• Clockify permits only one running timer. start_timer therefore stops any timer already running — the tool reports this explicitly rather than letting it happen silently.

• stop_timer with nothing running answers "No timer was running." rather than erroring.

• There is deliberately no update or delete tool, so the server cannot modify or destroy existing entries. The worst case is a spurious new entry you can remove in the web UI.

Development

npm run watch    # tsc --watch

Smoke-test the protocol without involving Claude:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | node dist/index.js

Only protocol messages go to stdout — anything else would corrupt the stream, so logs go to stderr.

Security

The API key is a bearer credential with full access to your Clockify time data. It sits in plaintext in .env, readable by anything running as your user; there is no OS keychain integration here.

The key never leaves your machine — it goes into an outbound header and is not sent to Anthropic. Tool results (project names, entry descriptions, durations) do become part of the conversation, so they reach the model like any other tool output.

Layout

src/time.ts       local <-> UTC conversion, ISO-8601 durations
src/clockify.ts   HTTP client, error mapping, cached identity lookup
src/tools.ts      the 8 tool registrations
src/index.ts      env loading, McpServer, stdio transport

Built on @modelcontextprotocol/server v2. Requires Node >= 20.