Clockify MCP Server

Instructions

Implementation Reference

• src/index.ts:1412-1470 (handler)

  The main handler function for the 'get_detailed_report' tool. It constructs a payload from input arguments and makes a POST request to Clockify's detailed reports API endpoint, then returns a summary of the report.
  const { workspaceId, ...reportData } = args; const payload = { dateRangeStart: reportData.dateRangeStart, dateRangeEnd: reportData.dateRangeEnd, detailedFilter: { sortColumn: reportData.sortColumn || "DATE", sortOrder: reportData.sortOrder || "DESCENDING", page: reportData.page || 1, pageSize: Math.min(reportData.pageSize || 50, 1000), options: { totals: "CALCULATE", }, }, users: reportData.users ? { ids: reportData.users } : undefined, clients: reportData.clients ? { ids: reportData.clients } : undefined, projects: reportData.projects ? { ids: reportData.projects } : undefined, tasks: reportData.tasks ? { ids: reportData.tasks } : undefined, tags: reportData.tags ? { ids: reportData.tags } : undefined, billable: reportData.billable, description: reportData.description, withoutDescription: reportData.withoutDescription, customFieldIds: reportData.customFieldIds, sortColumn: reportData.sortColumn, sortOrder: reportData.sortOrder, page: reportData.page, pageSize: reportData.pageSize, exportType: reportData.exportType || "JSON", }; // Remove undefined properties Object.keys(payload).forEach(key => { if (payload[key as keyof typeof payload] === undefined) { delete payload[key as keyof typeof payload]; } }); const report = await this.makeRequest( `/workspaces/${workspaceId}/reports/detailed`, "POST", payload, "https://reports.api.clockify.me/v1" ); const summary = `Detailed Report Summary: Total Entries: ${report.timeentries?.length || 0} Total Duration: ${report.totals?.[0]?.totalTime || "0:00:00"} Date Range: ${reportData.dateRangeStart} to ${reportData.dateRangeEnd}`; return { content: [ { type: "text", text: summary, }, ], isError: false, }; }
• src/index.ts:664-689 (registration)

  Tool registration in the ListToolsRequestSchema handler, defining the name, description, and input schema for 'get_detailed_report'.
  name: "get_detailed_report", description: "Generate a detailed time tracking report", inputSchema: { type: "object", properties: { workspaceId: { type: "string", description: "Workspace ID" }, dateRangeStart: { type: "string", description: "Start date (ISO 8601 format)" }, dateRangeEnd: { type: "string", description: "End date (ISO 8601 format)" }, users: { type: "array", items: { type: "string" }, description: "Array of user IDs to filter" }, clients: { type: "array", items: { type: "string" }, description: "Array of client IDs to filter" }, projects: { type: "array", items: { type: "string" }, description: "Array of project IDs to filter" }, tasks: { type: "array", items: { type: "string" }, description: "Array of task IDs to filter" }, tags: { type: "array", items: { type: "string" }, description: "Array of tag IDs to filter" }, billable: { type: "boolean", description: "Filter by billable status" }, description: { type: "string", description: "Filter by description" }, withoutDescription: { type: "boolean", description: "Filter entries without description" }, customFieldIds: { type: "array", items: { type: "string" }, description: "Array of custom field IDs" }, sortColumn: { type: "string", description: "Sort column (DATE, USER, PROJECT, etc.)" }, sortOrder: { type: "string", enum: ["ASCENDING", "DESCENDING"], description: "Sort order" }, page: { type: "number", description: "Page number (default: 1)" }, pageSize: { type: "number", description: "Page size (default: 50, max: 1000)" }, exportType: { type: "string", enum: ["JSON", "PDF", "CSV", "XLSX"], description: "Export format" }, }, required: ["workspaceId", "dateRangeStart", "dateRangeEnd"], }, },
• src/index.ts:813-814 (registration)

  Dispatch registration in the CallToolRequestSchema switch statement, routing calls to the getDetailedReport handler.
  case "get_detailed_report": return await this.getDetailedReport(args);
• src/index.ts:666-687 (schema)

  Input schema defining parameters and validation for the 'get_detailed_report' tool.
  inputSchema: { type: "object", properties: { workspaceId: { type: "string", description: "Workspace ID" }, dateRangeStart: { type: "string", description: "Start date (ISO 8601 format)" }, dateRangeEnd: { type: "string", description: "End date (ISO 8601 format)" }, users: { type: "array", items: { type: "string" }, description: "Array of user IDs to filter" }, clients: { type: "array", items: { type: "string" }, description: "Array of client IDs to filter" }, projects: { type: "array", items: { type: "string" }, description: "Array of project IDs to filter" }, tasks: { type: "array", items: { type: "string" }, description: "Array of task IDs to filter" }, tags: { type: "array", items: { type: "string" }, description: "Array of tag IDs to filter" }, billable: { type: "boolean", description: "Filter by billable status" }, description: { type: "string", description: "Filter by description" }, withoutDescription: { type: "boolean", description: "Filter entries without description" }, customFieldIds: { type: "array", items: { type: "string" }, description: "Array of custom field IDs" }, sortColumn: { type: "string", description: "Sort column (DATE, USER, PROJECT, etc.)" }, sortOrder: { type: "string", enum: ["ASCENDING", "DESCENDING"], description: "Sort order" }, page: { type: "number", description: "Page number (default: 1)" }, pageSize: { type: "number", description: "Page size (default: 50, max: 1000)" }, exportType: { type: "string", enum: ["JSON", "PDF", "CSV", "XLSX"], description: "Export format" }, }, required: ["workspaceId", "dateRangeStart", "dateRangeEnd"],