Clockify MCP Server

WARNING

⚠️ THIS HAS MOSTLY BEEN CODED VIA AI - PROCEED AT YOUR OWN RISK⚠️

Clockify MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with the Clockify time tracking API. This server enables AI assistants to interact with Clockify for time tracking, reporting, and team management tasks.

Features

Core Functionality

• 🔍 Find time entries by user, project, or search phrase
• ⏱️ Start and stop timers with project association
• ➕ Add time entries for any user with flexible parameters
• 📊 High-level analysis tools for team management
• 📈 Weekly summaries and overtime detection

High-Level Tools

• Find overtime users: Identify team members working >40 hours/week
• Find undertime users: Identify team members logging <20 hours/week
• Weekly summaries: Get detailed breakdowns of hours by week
• Project analytics: See who's working on what and for how long

Installation

Prerequisites

• Python 3.10 or higher
• Clockify API key (Get one here)

Quick Install with uvx

The easiest way to use this server is with uvx (bundled with uv):

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Run the server directly (it will be cached)
uvx clockify-mcp-server

Manual Installation

# Clone the repository
git clone https://github.com/yourusername/clockify-mcp-server.git
cd clockify-mcp-server

# Install with pip
pip install -e .

# Or install from PyPI (once published)
pip install clockify-mcp-server

Configuration

Environment Variables

Set your Clockify API key as an environment variable:

export CLOCKIFY_API_KEY="your_api_key_here"

You can get your API key from Clockify User Settings under "API" section.

MCP Client Configuration

Add this to your MCP client configuration file:

For Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "clockify": {
      "command": "uvx",
      "args": ["clockify-mcp-server"],
      "env": {
        "CLOCKIFY_API_KEY": "your_api_key_here"
      }
    }
  }
}

For Opencode

{
  "mcp": {
    "clockify": {
      "command": ["uvx", "clockify-mcp-server"]
      "environment": {
        "CLOCKIFY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Available Tools

1. `find_user_time_entries`

Find all time entries for a specific user.

Parameters:

• user_name (required): Name of the user (partial match, case-insensitive)
• start_date (optional): Start date in YYYY-MM-DD format (default: 30 days ago)
• end_date (optional): End date in YYYY-MM-DD format (default: today)
• limit (optional): Maximum entries to display (default: 50, use 0 for unlimited)
• workspace_id (optional): Workspace ID (default: user's default workspace)

Example:

Find all time entries for John Doe from the last 30 days

2. `find_project_time_entries`

Find all time entries for a specific project.

Parameters:

• project_name (required): Name of the project (partial match, case-insensitive)
• start_date (optional): Start date in YYYY-MM-DD format (default: 30 days ago)
• end_date (optional): End date in YYYY-MM-DD format (default: today)
• limit (optional): Maximum entries to display (default: 30, use 0 for unlimited)
• workspace_id (optional): Workspace ID

Example:

Show me all time logged to the "Website Redesign" project this month

3. `search_time_entries`

Search time entries by description phrase.

Parameters:

• search_phrase (required): Phrase to search for in descriptions
• user_name (optional): Limit search to specific user
• start_date (optional): Start date in YYYY-MM-DD format (default: 30 days ago)
• end_date (optional): End date in YYYY-MM-DD format (default: today)
• limit (optional): Maximum entries to display (default: 50, use 0 for unlimited)
• workspace_id (optional): Workspace ID

Example:

Find all time entries containing "meeting" in the description

4. `add_time_entry`

Add a time entry for a specific user.

Parameters:

• user_name (required): Name of the user
• description (required): Description of the work
• start_time (required): Start time in ISO format (e.g., 2024-01-29T09:00:00)
• end_time (required): End time in ISO format (e.g., 2024-01-29T17:00:00)
• project_name (optional): Project to associate with
• task_name (optional): Task within the project (requires project_name)
• billable (optional): Whether time is billable (default: true)
• workspace_id (optional): Workspace ID

Example:

Add a time entry for Jane Smith: 8 hours today on "Client Project" for meetings

5. `start_timer`

Start a timer for the current user.

Parameters:

• description (re