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

• Develop Prerequisites
• Publish Prerequisites

Install the plugin (once per machine)

1. Create a Clockify API key (Preferences → Advanced → Manage API Keys).
2. 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).
3. Reload Cursor; confirm Customize → MCP shows clockify-agent-plugin enabled.
4. 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)

1. 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).
2. 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