mcp-clockify

The MCP clockify is a Model Context Protocol (MCP) server that provides a simple integration with the Clockify API. This server allows you to interact with Clockify time tracking features through Claude and other MCP-compatible clients.

Features

This MCP server provides the following tools:

| Tool Name | Description | | --- | --- | | clockify_list_workspaces | List all workspaces available. | | clockify_get_user_info | Get user information. | | clockify_get_workspace_users | Get all users in a workspace. | | clockify_get_clients | Get all clients in a workspace. | | clockify_create_client | Create a new client. | | clockify_update_client | Update a client. | | clockify_delete_client | Delete a client. | | clockify_get_projects_info | Get information from all my projects. | | clockify_create_project | Create a new project. | | clockify_update_project | Update a project's information. | | clockify_delete_project | Delete a project. | | clockify_get_tasks | Get all tasks for a project. | | clockify_create_task | Create a new task in a project. | | clockify_update_task | Update a task. | | clockify_delete_task | Delete a task. | | clockify_get_time_entries | Get all time entries for my user. | | clockify_add_time_entry | Add a new time entry. | | clockify_delete_time_entry | Delete a time entry. | | clockify_update_time_entry | Update a time entry. | | clockify_stop_time_entry | Stop the currently running time entry. | | clockify_get_available_tags | Get all available tags in a workspace. | | clockify_create_tag | Create a new tag. | | clockify_update_tag | Update a tag. | | clockify_delete_tag | Delete a tag. | | clockify_get_time_off_requests | Get all time off requests in a workspace. | | clockify_create_time_off_request | Create a new time off request. | | clockify_change_time_off_request_status | Change the status of a time off request (approve/reject). | | clockify_get_time_off_policies | Get all time off policies in a workspace. | | clockify_get_dashboard_info | Get dashboard information and analytics for a workspace. | | clockify_get_timeline_for_reports | Get timeline data for time off requests in reports. | | clockify_get_users_for_report_filter | Get users available for report filtering. | | clockify_get_projects_for_report_filter | Get projects available for report filtering. | | clockify_get_clients_for_report_filter | Get clients available for report filtering. | | clockify_get_tasks_for_report_filter | Get tasks available for report filtering. |

Prerequisites

1. A Clockify account (free or paid)
2. A Clockify API key
3. Node.js installed on your system

Getting Your Clockify API Key

1. Log in to your Clockify account
2. Go to User Settings (click your profile picture in the top right)
3. Navigate to the API section in the left sidebar
4. Copy your API Key from the "Generated API key" field
5. If you don't have an API key yet, click Generate to create one

Installation

Option 1: Install from npm (Recommended)

npm install -g @crunchloop/mcp-clockify

Option 2: Build from source

1. Clone the repository:

git clone https://github.com/crunchloop/mcp-clockify.git
cd mcp-clockify

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

Environment Variable

The server requires a CLOCKIFY_API_KEY environment variable to authenticate with the Clockify API.

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

If installed via npm:

{
  "mcpServers": {
    "clockify": {
      "command": "clockify-mcp",
      "env": {
        "CLOCKIFY_API_KEY": "your-clockify-api-key-here"
      }
    }
  }
}

If built from source:

{
  "mcpServers": {
    "clockify": {
      "command": "node",
      "args": ["/path/to/mcp-clockify/dist/index.js"],
      "env": {
        "CLOCKIFY_API_KEY": "your-clockify-api-key-here"
      }
    }
  }
}

Other MCP Clients

For other MCP-compatible clients, use:

• Command: clockify-mcp (if installed via npm) or node /path/to/dist/index.js (if built from source)
• Environment: CLOCKIFY_API_KEY=your-clockify-api-key-here

Usage

Once configured, you can interact with Clockify through your MCP client. Here are some example interactions:

• "Show me my Clockify workspaces"
• "Get my user information from Clockify"
• "Show me my recent time entries"
• "Create a time entry for 2 hours of development work on Project X"
• "What tags are available in my workspace?"

Development

Updating the API Client

When Clockify's API changes or you need to update to the latest version:

npm run generate:client

This fetches the latest OpenAPI specification from Clockify and regenerates the TypeScript client. The generated files are committed to ensure reliable builds.

Running in Development Mode

1. Set your environment variable:

export CLOCKIFY_API_KEY=your-clockify-api-key-here

2. Run with the MCP inspector:

npm run debug

Publishing

The package automatically regenerates the client before publishing:

npm publish  # Runs generate:client -> build -> publish

License

MIT

Contributing

Issues and pull requests are welcome on the GitHub repository.