home / mcp / clockify mcp server

Clockify MCP Server

Provides Clockify data access and time-tracking actions via MCP for AI assistants, including time entries, timers, and weekly analytics.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

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

You can run and integrate Clockify with a Model Context Protocol (MCP) server to enable AI assistants to manage time tracking, reporting, and team management tasks against Clockify. This MCP server exposes a practical set of time-tracking commands and analytics that you can use from MCP clients to find, add, and summarize time entries, as well as monitor overtime and undertime across your team.

How to use

To use this MCP server, configure it as an MCP endpoint in your client and run the server locally or remotely via the provided command. Your MCP client will send requests to the server to find time entries, add entries, start or stop timers, and generate weekly summaries or team analytics. You can query by user, project, or search phrase, and you can enable or disable specific capabilities through the client configuration. Ensure you supply your Clockify API key so the server can access your Clockify data.

How to install

Prerequisites you need before installation:

Python 3.10 or higher

Clockify API key

Install via the quick method using uvx, which bundles uv and provides a straightforward run mode.

# 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

Additional setup and configuration

Environment configuration is required for Clockify access. Set your Clockify API key as an environment variable and reference it from the MCP client configuration.

export CLOCKIFY_API_KEY="your_api_key_here"

Manual installation

If you prefer to install manually, clone the project, install dependencies, and install the package in editable mode or from PyPI when available.

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

# Install with pip in editable mode
pip install -e .

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

Configuration for MCP clients

Add the MCP client configuration to point to this server. The recommended local setup uses uvx to run the MCP server. Example configurations are shown for common clients.

# Example for Claude Desktop
{
  "mcpServers": {
    "clockify": {
      "command": "uvx",
      "args": ["clockify-mcp-server"],
      "env": {
        "CLOCKIFY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Security and access

Keep your Clockify API key secure. Do not expose it in public configurations. Prefer storing secrets in a secure environment manager and reference them in your MCP client configuration.

Troubleshooting

If you encounter issues, verify that your Clockify API key is valid and that you have access to the necessary workspaces. Ensure your internet connection is stable and that no proxy is blocking API requests.

Notes

This server provides time-tracking operations and high-level analytics with weekly summaries and overtime/undertime detection to help you manage a team effectively within Clockify.

Available tools

find_user_time_entries

Find all time entries for a specific user with optional date range, limit, and workspace filters.

find_project_time_entries

Find all time entries associated with a specific project, with optional date range, limit, and workspace filters.

search_time_entries

Search time entries by a description phrase, with optional user, date range, and workspace filters.

add_time_entry

Add a new time entry for a specific user with required time and optional project/task details and workspace.

start_timer

Start a timer for the current user with optional project and task associations.

stop_timer

Stop the currently running timer for the user in a given workspace.

find_overtime_users

Identify users who exceed a weekly hours threshold within a given number of weeks.

find_undertime_users

Identify users who have logged less than a minimum required hours per week.

get_user_weekly_summary

Provide a weekly breakdown of hours for a specific user over a number of weeks.