Clockify

This Clockify MCP Server lets you interact with the Clockify time tracking API through MCP-compatible clients. It exposes a set of tools for managing workspaces, projects, time entries, and reporting, allowing you to automate and script common Clockify tasks from your preferred MCP client.

How to use

Once you configure your MCP client to talk to Clockify, you can perform common time-tracking tasks through simple tool calls. These tools auto-detect your user and workspace when possible and return human-friendly durations and summaries. You can start timers, stop running timers, log time, and generate summary or detailed reports. Use the tools to manage workspaces, projects, tasks, tags, and clients, then pull reports that group results by project, user, or client.

Typical usage patterns include starting a timer for a task, stopping the current timer, and logging a fixed duration for work completed. You can also query your current running timer to see elapsed time, fetch lists of workspaces and projects, and generate time reports for a chosen period.

To use advanced features, combine filters for projects, dates, or users when requesting time entries, or generate grouped reports that summarize time by project or client. All actions use clearly named tools exposed by the MCP server, so you don’t need to know API internals—just call the appropriate tool with your desired parameters.

How to install

Prerequisites: ensure you have Node.js and npm installed on your system.

Install the Clockify MCP Server globally so you can invoke it from any project or shell.

npm install -g @yikizi/clockify-mcp

Alternatively, run the MCP server directly without a global install using npx.

npx @yikizi/clockify-mcp

Configuration and credentials

Configure your Clockify API key in one of these ways, then point your MCP client to the Clockify MCP server.

Option A: CLI argument (recommended) — pass the API key when starting the MCP server through your client configuration.

{
  "mcpServers": {
    "clockify": {
      "command": "npx",
      "args": ["@yikizi/clockify-mcp", "--api-key", "your-api-key-here"]
    }
  }
}

Option B: Environment variable — set the API key in the environment passed to the MCP process.

{
  "mcpServers": {
    "clockify": {
      "command": "npx",
      "args": ["@yikizi/clockify-mcp"],
      "env": {
        "CLOCKIFY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Option C: Use a local .env file in your working directory with a line like this: CLOCKIFY_API_KEY=your-api-key-here

Notes on environment variables

If you provide the API key via the environment, the MCP server will read it from CLOCKIFY_API_KEY. You can also pass the key directly as a CLI argument when starting the MCP process, which is convenient for temporary sessions or scripts.

Security considerations

Treat your API key as sensitive data. Avoid hard-coding it in shared scripts or public repositories. Prefer environment variables or secure secret management when deploying the MCP server in multi-user environments.

Troubleshooting and tips

If you encounter authentication errors, double-check that CLOCKIFY_API_KEY is set correctly in the environment or that the API key you provided is valid for Clockify. Ensure the MCP client is configured to use the same key.

If you see issues with timer detection, verify that your Clockify account has the right permissions and that you’re targeting the correct workspace and user. Use the get_current_user and get_workspaces tools to confirm identity and scope.

Available tools

start_timer

Start a timer with a description and optional project to track time for a task.

stop_current_timer

Stop the currently running timer for the authenticated user.

get_running_timer

Check if a timer is running and view its elapsed time.

log_time

Log a completed time entry with a human-friendly duration like '1h30m'.

get_workspaces

List all workspaces accessible to the authenticated user.

get_current_user

Retrieve information about the authenticated user.

get_workspace_users

List users in a specific workspace.

get_projects

List projects within a workspace with optional archived filter.

create_project

Create a new project within a workspace.

get_project_tasks

List tasks within a project.

create_task

Create a new task within a project.

get_time_entries

Retrieve time entries for a user with optional date or project filters.

create_time_entry

Create a new time entry for a user.

stop_timer

Stop a timer for a specific user (alternative to stop_current_timer).

update_time_entry

Update fields of an existing time entry.

delete_time_entry

Delete a time entry.

get_summary_report

Generate an aggregated report grouped by project, user, or client.

get_detailed_report

Produce a detailed list of time entries with various filters.

get_tags

List all tags in the account.

create_tag

Create a new tag for organizing time entries.

get_clients

List all clients in the account.