Clockify MCP Server

A modular Model Context Protocol (MCP) server for integrating with the Clockify time tracking API.

Installation

From npm (Recommended)

From Source

Features

This MCP server provides three tools:

1. iam - Get current user information from Clockify API

2. getAllProjects - Get all projects for a specific workspace

3. logTimeEntry - Log time entries with flexible time specifications

Architecture

The server is built with a modular architecture:

• src/server.js - Main server class with registerTool interface

• src/api.js - Shared API utilities for Clockify requests

• src/tools/ - Individual tool modules with Zod schema validation

• index.js - Entry point that registers all tools

Setup

1. Set Environment Variables

Create a .env file or set the environment variable with your Clockify API key:

You can get your API key from Clockify Settings > API.

2. Run the Server

If installed globally:

If running from source:

Or for development with auto-restart:

Usage in MCP Clients

After installing, you can configure your MCP client to use this server. For example, in Claude Desktop:

Tools

iam

Get current user information from Clockify API.

Parameters: None

Example:

getAllProjects

Get all projects for a specific workspace.

Parameters:

• workspaceId (string, required): The workspace ID to get projects for

Example:

logTimeEntry

Log a time entry in Clockify.

Parameters:

• date (string, required): Date for the time entry in YYYY-MM-DD format

• description (string, required): Description of the work performed

• projectId (string, required): ID of the project to log time against

• workspaceId (string, required): ID of the workspace

• startTime (string, optional): Start time in HH:MM format (defaults to "09:00")

• endTime (string, optional): End time in HH:MM format (defaults to "17:00")

Example:

Getting Workspace and Project IDs

1. Use the iam tool to get your user information and available workspaces

2. Use the getAllProjects tool with a workspace ID to get project IDs

3. Use these IDs in the logTimeEntry tool

Error Handling

The server includes comprehensive error handling for:

• Missing or invalid API keys

• Invalid date/time formats

• Missing required parameters

• API request failures

• Time validation (end time must be after start time)

All errors are returned with descriptive messages to help troubleshoot issues.

Development

Adding New Tools

The server uses a clean registerTool interface. To add a new tool:

1. Create a new file in src/tools/ with your tool definition:

2. Export it from src/tools/index.js

3. Register it in index.js:

The server automatically handles:

• Zod schema validation

• JSON schema conversion for MCP

• Error handling and formatting

• Tool registration and discovery

Publishing

To publish updates to npm:

1. Update the version in package.json

2. Run npm publish

License

MIT

Requirements

• Node.js 18.0.0 or higher

• Clockify API key