Unofficial agent plugin for Clockify: MCP tools plus Agent Skills — start/stop timers, enter time, and summarize sessions in Cursor and other MCP hosts.

Not affiliated with, endorsed by, or sponsored by Clockify or Cake.com. Third-party connector only.

Features

Feature	Description	Documentation
Easy Installation	Single user-scoped MCP server utilizing a single Clockify API key	Config
Granular Repo Integration	Initialize and configure on a per-repo basis	Config
Easy Uninstallation	Skills and scripts rollback changes with guards to prevent overreach or harm	Use
Good Hygiene	Plugin artifacts are gitignored by default	Config: git hygiene
Three Time Entry Methods	Running timer, explicit start/stop times, automated using workflow triggers	schema
IDE Layouts	Supports: single-window, multi-window, multi-root code workspace	Config: which repo
Customize Time Entry	Configure nearest/up/down rounding, start/stop, increment, minimums, include seconds	schema: rounding
Overlap guards	Handle overlapping time entries based on config	schema: overlap
Init then Automate	`/clockify-init` pins workspace; `/clockify-automate` enables forge + Cursor Plan/Debug	Config: Init vs Automate
Description templates	Tokenized strings (`{issue_number}`, `{label}`, …) or agent prompt	schema: placeholders
Timer Runaway Prevention	Ask when a running timer exceeds a ceiling so Clockify is ready for automation	schema: runaway

How it works

Two modes. Both use the same Clockify project for a given repo config (when automate has ensured one). Clockify still allows only one running timer. Product ladder: Config: Init vs Automate.

Mode	How time gets in	Skills
Manual	You (or the agent, when you ask) start/stop a timer or log a completed range	`/clockify-start-timer`, `clockify-stop-timer`, `/clockify-enter-time`
Automated	Agent follows Cursor rules from `entry.automated` (forge issue/PR triggers + optional Plan/Debug)	`/clockify-automate` on; `/clockify-automate-disable` pause (keep settings); `/clockify-unautomate` full rollback

Getting started

Prerequisites

Need	Why
Node 18+ (npm / npx)	Install script and the MCP `npx` command
Cursor (or AI Agent/IDE)	Run skills and MCP
Clockify API key	MCP sevrver connection to Clockify

If Cursor cannot find node / npx, see troubleshoot. MCP process logs: logging.

Additional Prerequisites

Install the plugin (once per machine)

Create a Clockify API key (Preferences → Advanced → Manage API Keys).
Run npx -y -p @dustinestes/clockify-agent-plugin clockify-install-cursor — installs skills + global MCP (docs/install-cursor.md). Optional: Directory MCP button (MCP only; caveats).
Reload Cursor; confirm Customize → MCP shows clockify-agent-plugin enabled.
Optional: pre-allow Clockify MCP tools so agents do not stall on an Allow / Always allow prompt mid-run.

Credentials, allowlists, and non-Cursor hosts: docs/use.md.

Add Clockify to a repo (each repo)

In that repo, run /clockify-init — choose a Clockify workspace. Writes v3 .clockify/config.yml (prompt descriptions, timer starts without requiring a task; automation off). After this you can enter time with skills (start/stop timer, enter-time, summarize).
Optional: run /clockify-automate for forge (GitHub) + Cursor Plan/Debug + runaway, project/task ensure, Cursor rules, and runaway hooks when enabled.

To undo a repo without uninstalling the plugin: docs/use.md.

Skills

You talk to the agent in plain language (or run a /skill). The agent calls MCP tools; you do not.

Setup skills (init, uninit, automate, automate-disable, automate-enable, unautomate) are slash-only so they do not fire by accident.

Group	Skill	Purpose	Example
Repo	`clockify-init`	Pin workspace; write v3 base config + ignore defaults (no project ensure)	`/clockify-init`
Repo	`clockify-uninit`	Full local teardown (keep plugin unless asked)	`/clockify-uninit`
Mode	`clockify-automate`	Agent mode on: forge + Cursor Plan/Debug + runaway, ensure, rules, hooks when runaway enabled	`/clockify-automate`
Mode	`clockify-automate-disable`	Pause automate: remove rule/hooks; keep forge/triggers/modes (`enabled: false`)	`/clockify-automate-disable`
Mode	`clockify-automate-enable`	Resume after disable: flip flags on, rewrite rule/hooks from preserved settings	`/clockify-automate-enable`
Mode	`clockify-unautomate`	Agent mode off: remove rule/hooks; reset `entry.automated` to example defaults	`/clockify-unautomate`
Timer	`clockify-start-timer`	Start a running timer (`entry_method: timer`)	`/clockify-start-timer` or “start a timer on this issue”
Timer	`clockify-stop-timer`	Stop the running timer	`/clockify-stop-timer` or “stop my Clockify timer”
Timer	`clockify-status`	Read-only running timer (or none)	`/clockify-status` or “is a timer running?”
Time	`clockify-enter-time`	Completed range, no rounding (`entry_method: manual`)	`/clockify-enter-time` or “log 2–3pm on this issue”
Review	`clockify-summarize`	Today / range totals	`/clockify-summarize` or “how much time today?”

Developing

Working on this repo: docs/develop.md. Shipping a release or Directory listing: docs/publish.md. How to contribute: CONTRIBUTING.md.

Clockify Agent Plugin

MIT License

Clockify MCP Server