clockify-mcp-server

Erfasse deine Projektstunden in Clockify, indem du deinen Agenten darum bittest, statt durch die Weboberfläche zu klicken.

„Erfasse diese Woche jeden Morgen 4h für ACME und jeden Nachmittag 4h für Evil Corp“

→ ein einziger Bestätigungsprompt, 10 Einträge erstellt, insgesamt 40h.

Ein lokaler stdio-MCP-Server. Jede Person führt ihn selbst mit dem eigenen API-Key aus — nichts wird geteilt oder gehostet.

Zeiten sind immer lokal in der Zeitzone deines Clockify-Profils. Du sagst 09:00, der Server liest settings.timeZone aus deinem Clockify-Profil und rechnet in UTC um. Du hast nie mit UTC zu tun — und der Agent auch nicht.

Noch nicht unterstützt: Tags, Clients, laufende Timer (Start/Stopp), Bearbeiten vorhandener Einträge, Reports.

Benutzung

Alles, was du brauchst, wenn du nur Zeiterfassen willst. Dauert etwa zwei Minuten.

1. Installiere bun (getestet mit Version 1.3.14) und die Abhängigkeiten:

curl -fsSL https://bun.sh/install | bash # install bun if needed
git clone <this-repo> && cd clockify-mcp-server
bun install

Es gibt keinen Build-Schritt — bun führt das TypeScript direkt aus.

2. Besorge dir deinen Clock-API-Key:

• Clockify → dein Avatar → Einstellungen → Reiter Erweitert → API-Keys verwalten → Neu generieren

3. Registriere den Server bei deinem Agent.

Claude Code — kopiere das unverändert aus dem Repo-Root-Verzeichnis, das du gerade geklont hast:

claude mcp add clockify -s user -e CLOCKIFY_API_KEY=<key> -- bun "$PWD/src/index.ts"

Das -s user schreibt es in deine persönliche Konfiguration, so dass es in jedem Projekt geladen wird, nicht nur in diesem Projekt (der Standard-Scope local würde es an dieses Verzeichnis binden). $PWD wird von deiner Shell expandiert, bevor claude sie sieht, der gespeicherte Pfad ist also absolut.

Für jede andere Umgebung (Cursor, VS Code, Zed, Claude Desktop …) — dieselben drei Dinge in deiner MCP-Konfiguration. Gib dir den Pfad ein:

echo "$PWD/src/index.ts"

{
  "mcpServers": {
    "clockify": {
      "command": "bun",
      "args": ["<paste the absolute path here>"],
      "env": { "CLOCKIFY_API_KEY": "<key>" }
    }
  }
}

Der Pfad muss absolut sein: dein Agent startet den Server aus dem Verzeichnis, in dem er gerade arbeitet, und nicht aus diesem Repo.

4. Teste es — in einer neuen Sitzung:

list my clockify projects
log 2 hours on <project> today from 09:00 to 11:00, description test
show my clockify entries for this week
delete that entry

Öffne die Clock-UI nach dem zweiten Prompt und prüfe, ob der Eintrag 09:00–11:00 anzeigt. Wenn der eine andere Zeit steht, die Zeitzone in deinem Clockify-Profil nicht so ist, wie du denkst — korrigiere sie in den Clock-Einstellungen; von ihr hängt alles andere ab.

Umgebung

If this is wrong

• CLOCKIFY_API_KEY is not set — der API-Key hat den Serverprozess nicht erreicht. Lege ihn in die env-Sektion der Konfiguration deiner Umgebung, nicht in die Shell.

• Ambiguous project "x". Candidates: … — Absicht. The server refuses to rate; from one of the listed names.

• 404s whenever you add — dein Workspace liegt auf einem regionalen Host. Setze CLOCKIFY_API_BASE.

• Einträge landen zur falschen Stunde — check your profile timezone (see step 4).

Develop it

Nichts davon ist nötig, wenn du den Server nur zu benutzen willst.

bun test      # unit tests, no network
bun run check # biome format + lint, applies fixes
bun run start # start the server on stdio (needs CLOCKIFY_API_KEY)

bun install installiert auch die Git-Hooks (prepare → lefthook install), so dass biome check --write - Dateien beim Commit ausführt und das wieder zur Staging-Area hinzufügt, das er falls fixed. Nothing else is needed to be set.

Bei lokalen Läufen lädt bun automatically a .env from the repo root; a CLOCKIFY_API_KEY=<key> in einer .gitignore-ausgeschlossenen .env erspart dir dann das erneute Tippen. That works only if the current working directory is the repo itself; that's why the Harness configuration above passes the key explicitly.

Layout

src/clockify.ts      # API client, memoised user/project/task lookups, timezone conversion
src/index.ts         # McpServer + the four tools + stdio wiring
src/clockify.test.ts # the parts worth testing: DST conversion, name resolution, payload building
docs/                # Clockify API request/response samples
plans/               # what was built and what was deliberately left out

The interesting code is localToUtc / interval in src/clockify.ts — a stdlib Intl.DateTimeFormat round-trip, no date library. Changing it and bun test runs; the DST cases are those that catch mistakes.

If you want to ship it to someone without bun: bun build --compile --outfile clockify-mcp src/index.ts erzeugt a single self-contained binary that you can point the harness to.