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 runningget_running_timer- Check if a timer is running and see elapsed timelog_time- Log completed time with human-readable duration ("1h30m", "2h", "45m")
Workspace Tools
get_workspaces- List all workspacesget_current_user- Get authenticated user infoget_workspace_users- List users in a workspace
Project Tools
get_projects- List projects (with archive filter)create_project- Create a new projectget_project_tasks- List tasks in a projectcreate_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 (usestart_timerorlog_timeinstead)stop_timer- Stop timer for specific user (usestop_current_timerinstead)update_time_entry- Update an existing entrydelete_time_entry- Delete a time entry
Reporting Tools
get_summary_report- Aggregated report grouped by project/user/clientget_detailed_report- Detailed list of time entries with filters
Tag & Client Tools
get_tags- List all tagscreate_tag- Create a new tagget_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-keyCLI argument - Config: API key can be read from
.envfile in current directory - Improvement: Better error message showing all config options
v1.2.1
- Bugfix:
get_running_timernow properly finds running timers (was only checking 1 entry) - Bugfix:
stop_current_timernow correctly stops timers - Improvement:
stop_current_timeraccepts optionalendtime for backdating
v1.2.0
- Human-readable durations in responses (
1h 30minstead ofPT1H30M) - Relative period filters for
get_time_entries:today,yesterday,this_week,last_week,this_month,last_month get_time_entriesnow 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_userfirst) - 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
