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

1. Go to Clockify User Settings
2. Scroll to "API" section
3. 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