Clockify MCP Server

An MCP (Model Context Protocol) server that provides tools for interacting with the Clockify time tracking API.

Installation

npm install -g @yikizi/clockify-mcp

Or use directly with npx:

npx @yikizi/clockify-mcp

Features

Workspace Management: List workspaces, get current user, list workspace users
Project Management: List/create projects, list/create tasks
Time Tracking: Start/stop timers, log time entries, update/delete entries
Reporting: Generate summary and detailed reports with grouping and filtering
Tags & Clients: List and create tags, list clients

Setup

1. Get your Clockify API Key

Go to Clockify User Settings
Scroll to "API" section
Click "Generate" to create an API key

2. Configure Claude Code

Add to your Claude Code MCP settings (~/.claude.json or via Claude Code settings):

Option A: CLI argument (recommended)

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

Option B: Environment variable

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

Option C: .env file

Create a .env file in your working directory:

CLOCKIFY_API_KEY=your-api-key-here

Available Tools

Convenience Tools (Recommended)

These auto-detect your user and workspace:

start_timer - Start a timer (just provide description and optional project)
stop_current_timer - Stop whatever timer is running
get_running_timer - Check if a timer is running and see elapsed time
log_time - Log completed time with human-readable duration ("1h30m", "2h", "45m")

Workspace Tools

get_workspaces - List all workspaces
get_current_user - Get authenticated user info
get_workspace_users - List users in a workspace

Project Tools

get_projects - List projects (with archive filter)
create_project - Create a new project
get_project_tasks - List tasks in a project
create_task - Create a task

Time Entry Tools (Low-level)

get_time_entries - Get time entries for a user (with date/project filters)
create_time_entry - Create a time entry (use start_timer or log_time instead)
stop_timer - Stop timer for specific user (use stop_current_timer instead)
update_time_entry - Update an existing entry
delete_time_entry - Delete a time entry

Reporting Tools

get_summary_report - Aggregated report grouped by project/user/client
get_detailed_report - Detailed list of time entries with filters

Tag & Client Tools

get_tags - List all tags
create_tag - Create a new tag
get_clients - List all clients

Usage Examples

Once configured, you can ask Claude things like:

"Start a timer for working on the API project"
"Stop my timer"
"Log 2 hours for documentation work"
"Is my timer running?"
"Generate a summary report for last week"
"How much time did I log this month?"
"List all my projects"

Changelog

v1.2.2

Config: API key can now be passed via --api-key CLI argument
Config: API key can be read from .env file in current directory
Improvement: Better error message showing all config options

v1.2.1

Bugfix: get_running_timer now properly finds running timers (was only checking 1 entry)
Bugfix: stop_current_timer now correctly stops timers
Improvement: stop_current_timer accepts optional end time for backdating

v1.2.0

Human-readable durations in responses (1h 30m instead of PT1H30M)
Relative period filters for get_time_entries: today, yesterday, this_week, last_week, this_month, last_month
get_time_entries now defaults to current user/workspace (no IDs needed!)
Responses include total time across all entries

v1.1.0

Added convenience tools: start_timer, stop_current_timer, get_running_timer, log_time
Auto-detect user and workspace (no need to call get_current_user first)
Human-readable duration format ("1h30m") for log_time
Input validation to catch date typos early
Warns if timer is already running when starting a new one

v1.0.0

Initial release with core Clockify API support

License

MIT