Clockify MCP Server

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

Installation

From npm (Recommended)

npm install -g clockify-mcp-server

From Source

git clone https://github.com/yourusername/clockify-mcp-server.git
cd clockify-mcp-server
npm install

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:

export CLOCKIFY_API_KEY=your_api_key_here

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

2. Run the Server

If installed globally:

clockify-mcp-server

If running from source:

npm start

Or for development with auto-restart:

npm run dev

Usage in MCP Clients

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

{
  "mcpServers": {
    "clockify": {
      "command": "clockify-mcp-server",
      "env": {
        "CLOCKIFY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Tools

iam

Get current user information from Clockify API.

Parameters: None

Example:

{
  "name": "iam"
}

getAllProjects

Get all projects for a specific workspace.

Parameters:

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

Example:

{
  "name": "getAllProjects",
  "arguments": {
    "workspaceId": "60c1beaf8747147d9ac70b4b"
  }
}

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:

{
  "name": "logTimeEntry",
  "arguments": {
    "date": "2024-01-15",
    "description": "Working on project documentation",
    "projectId": "662f81c0b682f06d79bff487",
    "workspaceId": "60c1beaf8747147d9ac70b4b",
    "startTime": "09:30",
    "endTime": "12:30"
  }
}

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:

import { z } from "zod";
import { makeApiRequest } from "../api.js";

export const myNewTool = {
  name: "myNewTool",
  config: {
    title: "My New Tool",
    description: "Description of what the tool does",
    inputSchema: z.object({
      param1: z.string().describe("Description of param1"),
      param2: z.number().optional().describe("Optional param2")
    })
  },
  handler: async ({ param1, param2 }) => {
    // Your tool logic here
    const result = await makeApiRequest("/some-endpoint");
    return {
      content: [{
        type: "text",
        text: JSON.stringify(result, null, 2)
      }]
    };
  }
};

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

3. Register it in index.js:

server.registerTool(
  myNewTool.name,
  myNewTool.config,
  myNewTool.handler
);

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