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"], },