Clockify MCP Server

Instructions

Implementation Reference

• src/index.ts:947-973 (handler)

  The handler function that updates a time entry by making a PUT request to the Clockify API endpoint `/workspaces/{workspaceId}/time-entries/{timeEntryId}` with the provided update data. It handles date formatting and returns a success message.

  private async updateTimeEntry(args: any) {
    const { workspaceId, timeEntryId, ...updateData } = args;
  
    // Ensure dates are in ISO format
    if (updateData.start && !updateData.start.includes("T")) {
      updateData.start = new Date(updateData.start).toISOString();
    }
    if (updateData.end && !updateData.end.includes("T")) {
      updateData.end = new Date(updateData.end).toISOString();
    }
  
    const timeEntry = await this.makeRequest(
      `/workspaces/${workspaceId}/time-entries/${timeEntryId}`,
      "PUT",
      updateData
    );
  
    return {
      content: [
        {
          type: "text",
          text: `Time entry updated successfully!\nID: ${timeEntry.id}\nDescription: ${timeEntry.description || "No description"}\nStart: ${timeEntry.timeInterval.start}\nEnd: ${timeEntry.timeInterval.end || "Ongoing"}`,
        },
      ],
      isError: false,
    };
  }

• src/index.ts:326-342 (schema)

  The input schema definition for the update_time_entry tool, specifying parameters like workspaceId (required), timeEntryId (required), description, start, end, projectId, taskId, tagIds, and billable.

  name: "update_time_entry",
  description: "Update an existing time entry",
  inputSchema: {
    type: "object",
    properties: {
      workspaceId: { type: "string", description: "Workspace ID" },
      timeEntryId: { type: "string", description: "Time entry ID" },
      description: { type: "string", description: "Time entry description" },
      start: { type: "string", description: "Start time (ISO 8601 format)" },
      end: { type: "string", description: "End time (ISO 8601 format)" },
      projectId: { type: "string", description: "Project ID" },
      taskId: { type: "string", description: "Task ID" },
      tagIds: { type: "array", items: { type: "string" }, description: "Array of tag IDs" },
      billable: { type: "boolean", description: "Whether the entry is billable" },
    },
    required: ["workspaceId", "timeEntryId"],
  },

• src/index.ts:737-739 (registration)

  The registration and dispatch logic in the CallToolRequestSchema handler's switch statement, which validates required arguments and calls the updateTimeEntry handler.

  case "update_time_entry":
    if (!args?.workspaceId || !args?.timeEntryId) throw new McpError(ErrorCode.InvalidParams, 'workspaceId and timeEntryId are required');
    return await this.updateTimeEntry(args as any);

• src/index.ts:325-343 (registration)

  The tool registration in the ListToolsRequestSchema response, listing the update_time_entry tool with its name, description, and input schema.

  {
    name: "update_time_entry",
    description: "Update an existing time entry",
    inputSchema: {
      type: "object",
      properties: {
        workspaceId: { type: "string", description: "Workspace ID" },
        timeEntryId: { type: "string", description: "Time entry ID" },
        description: { type: "string", description: "Time entry description" },
        start: { type: "string", description: "Start time (ISO 8601 format)" },
        end: { type: "string", description: "End time (ISO 8601 format)" },
        projectId: { type: "string", description: "Project ID" },
        taskId: { type: "string", description: "Task ID" },
        tagIds: { type: "array", items: { type: "string" }, description: "Array of tag IDs" },
        billable: { type: "boolean", description: "Whether the entry is billable" },
      },
      required: ["workspaceId", "timeEntryId"],
    },
  },

• src/index.ts:203-247 (helper)

  The makeRequest helper method used by the updateTimeEntry handler to perform the API call to Clockify.

  private async makeRequest(
    endpoint: string,
    method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" = "GET",
    data?: any,
    baseUrl?: string
  ): Promise<any> {
    if (!this.config.apiKey) {
      throw new McpError(
        ErrorCode.InvalidParams,
        "Clockify API key not configured. Set CLOCKIFY_API_KEY environment variable."
      );
    }
  
    const url = `${baseUrl || this.config.baseUrl}${endpoint}`;
    const headers: Record<string, string> = {
      "X-Api-Key": this.config.apiKey,
      "Content-Type": "application/json",
    };
  
    try {
      const response = await fetch(url, {
        method,
        headers,
        body: data ? JSON.stringify(data) : undefined,
      });
  
      if (!response.ok) {
        const errorText = await response.text();
        throw new McpError(
          ErrorCode.InternalError,
          `Clockify API error (${response.status}): ${errorText}`
        );
      }
  
      return response.json();
    } catch (error) {
      if (error instanceof McpError) {
        throw error;
      }
      throw new McpError(
        ErrorCode.InternalError,
        `Request failed: ${error instanceof Error ? error.message : String(error)}`
      );
    }
  }