Clockify MCP server

clockify-mcp — Clockify MCP Server for Claude Code

An MCP server for Clockify time tracking. Start and stop timers, manage time entries, projects, tasks, tags, and clients — directly from Claude Code or any MCP-compatible client.

What is Clockify?

Clockify is a free time tracking tool used by freelancers and teams to log work hours, generate reports, and manage projects. It works across web, desktop, and mobile — and its generous free tier covers unlimited users and tracking. This MCP server lets you control Clockify with natural language through Claude, so you never have to leave your terminal.

Prerequisites

• A Clockify account — sign up for free (the free plan is all you need)
• A personal API key — once logged in, go to Profile settings → API → Generate
• Your workspace ID — visible in the Clockify URL after selecting a workspace (e.g. app.clockify.me/workspaces/<id>/...)
• Node.js 24+

Install

npm install -g @themkn/clockify-mcp

The binary is called clockify-mcp regardless of the scoped package name.

(Or point Claude's MCP config at the built JS locally — see below.)

Configure

The server reads a JSON config from ~/.clockify-mcp/config.json. Create it with permission 600:

mkdir -p ~/.clockify-mcp
chmod 700 ~/.clockify-mcp
cat > ~/.clockify-mcp/config.json <<'EOF'
{
  "apiKey": "YOUR_CLOCKIFY_PERSONAL_API_KEY",
  "workspaceId": "YOUR_WORKSPACE_ID"
}
EOF
chmod 600 ~/.clockify-mcp/config.json

Paste the API key and workspace ID from the prerequisites above. The server will refuse to start if the config file is group- or world-readable.

Hook into Claude Code

Add an entry to your Claude MCP config (typically ~/.config/claude/mcp.json or the per-project .claude/mcp.json):

{
  "mcpServers": {
    "clockify": {
      "command": "clockify-mcp"
    }
  }
}

Recommended permissions

By default Claude Code asks for permission on every Clockify tool call. A blanket mcp__clockify__* allow works, but it also auto-approves destructive calls like delete_time_entry. A tiered policy keeps the daily flow frictionless while making destructive or rare operations explicit.

Add this to your ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__clockify__get_current_user",
      "mcp__clockify__get_workspace",
      "mcp__clockify__get_project",
      "mcp__clockify__get_time_entry",
      "mcp__clockify__get_running_timer",
      "mcp__clockify__list_clients",
      "mcp__clockify__list_projects",
      "mcp__clockify__list_tasks",
      "mcp__clockify__list_tags",
      "mcp__clockify__list_time_entries",
      "mcp__clockify__start_timer",
      "mcp__clockify__stop_timer",
      "mcp__clockify__create_time_entry",
      "mcp__clockify__update_time_entry"
    ]
  }
}

What this does:

• Reads + time-entry writes (the list above) run without prompting — these are the daily flow.
• Catalog writes (create_project, update_client, etc.) and all delete_* tools are not listed, so Claude Code will prompt before each call. Catalog edits are rare from the MCP and deletes should be deliberate.

If you want a stricter setup, keep a wildcard allow and add a deny block for the destructive tools — deny blocks the call entirely (no prompt, no override):

{
  "permissions": {
    "allow": ["mcp__clockify__*"],
    "deny": [
      "mcp__clockify__delete_client",
      "mcp__clockify__delete_project",
      "mcp__clockify__delete_task",
      "mcp__clockify__delete_tag",
      "mcp__clockify__delete_time_entry"
    ]
  }
}

Tools

Grouped by resource:

Resource	Tools
Time entries	list_time_entries, get_time_entry, create_time_entry, update_time_entry, delete_time_entry, start_timer, stop_timer, get_running_timer
Projects	list_projects, get_project, create_project, update_project, delete_project
Tasks	list_tasks, create_task, update_task, delete_task
Tags	list_tags, create_tag, update_tag, delete_tag
Clients	list_clients, create_client, update_client, delete_client
Meta	get_current_user, get_workspace

Notes:

• All timestamps are ISO 8601 (YYYY-MM-DDTHH:mm:ssZ). Claude interprets relative phrases like "yesterday 9am" before calling the tool.
• Tools accept IDs, not names. Claude lists projects/tasks/tags/clients first, picks the matching id, then acts.
• delete_project tries a hard delete; if Clockify refuses because the project has time entries, the server archives it instead. The response reports { "action": "deleted" } or { "action": "archived" }.

Example prompts

Once the server is running, try asking Claude things like:

Prompt	What happens
"Start a timer for the standup meeting"	Starts a running timer with that description
"Stop my timer"	Stops the currently running timer
"How many hours did I log this week?"	Lists recent time entries and totals them
"Log 2 hours yesterday for the Website Redesign project"	Creates a time entry on the right project
"Create a project called 'Brand Refresh' for client Acme"	Creates a new project linked to an existing client
"Show me all time entries from last Monday"	Fetches entries filtered by date
"Tag my last time entry with 'billable'"	Updates the most recent entry with a tag
"Delete the 'test-cleanup' tag"	Removes a tag by name
"What projects do we have?"	Lists all projects in the workspace
"Am I tracking time right now?"	Checks for a running timer

Claude handles the translation from natural language to API calls — you just describe what you want in plain English.

Security

• The API key in ~/.clockify-mcp/config.json grants full access to your Clockify account. This server cannot narrow that scope — Clockify's API does not offer read-only personal tokens. Rotate the key if you suspect exposure.
• The key is never logged or returned in any tool response. Errors are scrubbed defensively before being surfaced.
• The only network destination is https://api.clockify.me; there is no telemetry.
• Run the server as your user — never via sudo.

Report vulnerabilities per SECURITY.md.

Development

npm install
npm run typecheck
npm test
npm run build

Optional: add npm run test:live later for integration tests against a real workspace (not run in CI).

License

MIT — see LICENSE.