Clockify MCP Server

Instructions

Implementation Reference

• src/index.ts:911-945 (handler)

  The main handler function for the 'get_time_entries' tool. It constructs the API endpoint for fetching time entries from Clockify, handles query parameters for filtering, calls the makeRequest method, and formats the response as MCP content.

  private async getTimeEntries(args: any) {
    const { workspaceId, userId, ...params } = args;
    
    // Build query parameters
    const queryParams = new URLSearchParams();
    Object.entries(params).forEach(([key, value]) => {
      if (value !== undefined && value !== null) {
        queryParams.append(key, String(value));
      }
    });
  
    const endpoint = userId 
      ? `/workspaces/${workspaceId}/user/${userId}/time-entries`
      : `/workspaces/${workspaceId}/time-entries`;
    
    const fullEndpoint = queryParams.toString() 
      ? `${endpoint}?${queryParams.toString()}`
      : endpoint;
  
    const timeEntries = await this.makeRequest(fullEndpoint);
  
    return {
      content: [
        {
          type: "text",
          text: `Found ${timeEntries.length} time entries:\n${timeEntries
            .map((entry: any) => 
              `- ${entry.description || "No description"} | ${entry.timeInterval.start} - ${entry.timeInterval.end || "Ongoing"} | ${entry.timeInterval.duration || "Running"}`
            )
            .join("\n")}`,
        },
      ],
      isError: false,
    };
  }

• src/index.ts:301-322 (schema)

  Input schema definition for the 'get_time_entries' tool, specifying parameters like workspaceId (required), userId, date filters, project/task/tag filters, pagination, etc.

  name: "get_time_entries",
  description: "Get time entries for a user",
  inputSchema: {
    type: "object",
    properties: {
      workspaceId: { type: "string", description: "Workspace ID" },
      userId: { type: "string", description: "User ID (optional, defaults to current user)" },
      description: { type: "string", description: "Filter by description" },
      start: { type: "string", description: "Start date filter (ISO 8601)" },
      end: { type: "string", description: "End date filter (ISO 8601)" },
      project: { type: "string", description: "Filter by project ID" },
      task: { type: "string", description: "Filter by task ID" },
      tags: { type: "string", description: "Filter by tag IDs (comma-separated)" },
      projectRequired: { type: "boolean", description: "Filter entries that require project" },
      taskRequired: { type: "boolean", description: "Filter entries that require task" },
      consideredRunning: { type: "boolean", description: "Include running time entries" },
      hydrated: { type: "boolean", description: "Include additional data" },
      inProgress: { type: "boolean", description: "Filter by running status" },
      page: { type: "number", description: "Page number (default: 1)" },
      pageSize: { type: "number", description: "Page size (default: 50, max: 5000)" },
    },
    required: ["workspaceId"],

• src/index.ts:734-736 (registration)

  Registration of the 'get_time_entries' handler in the CallToolRequestSchema switch statement, validating workspaceId and delegating to the getTimeEntries method.

  case "get_time_entries":
    if (!args?.workspaceId) throw new McpError(ErrorCode.InvalidParams, 'workspaceId is required');
    return await this.getTimeEntries(args as any);

• src/index.ts:17-26 (schema)

  TypeScript interface defining the structure of a TimeEntry object, used in the context of time entry tools.

  interface TimeEntry {
    id?: string;
    description?: string;
    start: string;
    end?: string;
    projectId?: string;
    taskId?: string;
    tagIds?: string[];
    billable?: boolean;
  }

• src/index.ts:281-323 (registration)

  Tool registration in the ListToolsRequestSchema response, including name, description, and inputSchema for 'get_time_entries'.

  // Time Entry Management
  {
    name: "create_time_entry",
    description: "Create a new time entry",
    inputSchema: {
      type: "object",
      properties: {
        workspaceId: { type: "string", description: "Workspace 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, optional for ongoing entries)" },
        projectId: { type: "string", description: "Project ID (optional)" },
        taskId: { type: "string", description: "Task ID (optional)" },
        tagIds: { type: "array", items: { type: "string" }, description: "Array of tag IDs (optional)" },
        billable: { type: "boolean", description: "Whether the entry is billable (optional)" },
      },
      required: ["workspaceId", "start"],
    },
  },
  {
    name: "get_time_entries",
    description: "Get time entries for a user",
    inputSchema: {
      type: "object",
      properties: {
        workspaceId: { type: "string", description: "Workspace ID" },
        userId: { type: "string", description: "User ID (optional, defaults to current user)" },
        description: { type: "string", description: "Filter by description" },
        start: { type: "string", description: "Start date filter (ISO 8601)" },
        end: { type: "string", description: "End date filter (ISO 8601)" },
        project: { type: "string", description: "Filter by project ID" },
        task: { type: "string", description: "Filter by task ID" },
        tags: { type: "string", description: "Filter by tag IDs (comma-separated)" },
        projectRequired: { type: "boolean", description: "Filter entries that require project" },
        taskRequired: { type: "boolean", description: "Filter entries that require task" },
        consideredRunning: { type: "boolean", description: "Include running time entries" },
        hydrated: { type: "boolean", description: "Include additional data" },
        inProgress: { type: "boolean", description: "Filter by running status" },
        page: { type: "number", description: "Page number (default: 1)" },
        pageSize: { type: "number", description: "Page size (default: 50, max: 5000)" },
      },
      required: ["workspaceId"],
    },