Clockify MCP

Instructions

Implementation Reference

• src/handlers.ts:182-200 (handler)

  Implements the getTimeEntries tool by fetching the current user's time entries from the Clockify API, optionally filtered by start and end dates, and returns them as JSON.

  case "getTimeEntries": {
    const { start, end } = request.params.arguments || {};
    let url = `/workspaces/${workspaceId}/user/${userId}/time-entries`;
    const params = [];
    if (typeof start === "string" && start)
      params.push(`start=${encodeURIComponent(start)}`);
    if (typeof end === "string" && end)
      params.push(`end=${encodeURIComponent(end)}`);
    if (params.length) url += `?${params.join("&")}`;
    const entries = await clockifyFetch(url);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(entries, null, 2),
        },
      ],
    };
  }

• src/handlers.ts:43-61 (schema)

  Defines the tool name, description, and input schema for getTimeEntries in the listToolsHandler response.

  {
    name: "getTimeEntries",
    description:
      "List time entries for the authenticated user. Optional: start, end (ISO8601).",
    inputSchema: {
      type: "object",
      properties: {
        start: {
          type: "string",
          description: "Start date (ISO8601, optional)",
        },
        end: {
          type: "string",
          description: "End date (ISO8601, optional)",
        },
      },
      required: [],
    },
  },

• src/index.ts:43-43 (registration)

  Registers the listToolsHandler which includes the getTimeEntries tool definition.

  server.setRequestHandler(ListToolsRequestSchema, listToolsHandler);

• src/index.ts:49-49 (registration)

  Registers the callToolHandler which dispatches to the getTimeEntries implementation.

  server.setRequestHandler(CallToolRequestSchema, callToolHandler);

• src/handlers.ts:13-32 (helper)

  Helper function used by getTimeEntries handler to make authenticated API calls to Clockify.

  async function clockifyFetch(endpoint: string, options: RequestInit = {}) {
    const apiKey = getApiKey();
    const baseUrl = "https://api.clockify.me/api/v1";
    const url = endpoint.startsWith("http") ? endpoint : `${baseUrl}${endpoint}`;
    const headers = {
      "X-Api-Key": apiKey,
      "Content-Type": "application/json",
      ...(options.headers || {}),
    };
    const response = await fetch(url, { ...options, headers });
  
    if (!response.ok) {
      const text = await response.text();
      console.error(
        `[Error] Clockify API ${url} failed: ${response.status} ${text}`,
      );
      throw new Error(`Clockify API error: ${response.status} ${text}`);
    }
    return response.json();
  }