Clockify MCP

Instructions

Implementation Reference

• src/handlers.ts:297-329 (handler)

  Handler function for the 'getUserTimeEntriesByName' tool. It finds a user by partial, case-insensitive name match from the workspace users, then fetches their time entries for the optional start/end date range using the Clockify API.

  case "getUserTimeEntriesByName": {
    const { userName, start, end } = request.params.arguments || {};
    if (!userName || typeof userName !== "string") {
      throw new Error("userName is required");
    }
    // Fetch users
    const users = await clockifyFetch(`/workspaces/${workspaceId}/users`);
    // Define a type for user
    type User = { id: string; name: string };
    // Find user by name (case-insensitive, partial match)
    const userMatch = (users as User[]).find(
      (u) => u.name && u.name.toLowerCase().includes(userName.toLowerCase()),
    );
    if (!userMatch) {
      throw new Error(`No user found matching name: ${userName}`);
    }
    let url = `/workspaces/${workspaceId}/user/${userMatch.id}/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:127-149 (schema)

  Input schema definition for the 'getUserTimeEntriesByName' tool, including parameters userName (required), start, end (optional).

  {
    name: "getUserTimeEntriesByName",
    description:
      "List time entries for a user by name (case-insensitive, partial match allowed). Optional: start, end (ISO8601).",
    inputSchema: {
      type: "object",
      properties: {
        userName: {
          type: "string",
          description: "User name (partial/case-insensitive)",
        },
        start: {
          type: "string",
          description: "Start date (ISO8601, optional)",
        },
        end: {
          type: "string",
          description: "End date (ISO8601, optional)",
        },
      },
      required: ["userName"],
    },
  },

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

  Registers the tool listing and calling handlers with the MCP server, which exposes and implements the 'getUserTimeEntriesByName' tool among others.

  server.setRequestHandler(ListToolsRequestSchema, listToolsHandler);
  
  /**
   * Handler for the create_note tool.
   * Creates a new note with the provided title and content, and returns success message.
   */
  server.setRequestHandler(CallToolRequestSchema, callToolHandler);

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

  Helper function to make authenticated API calls to Clockify, used by the tool handler to fetch users and time entries.

  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();
  }