Clockify MCP Server

Instructions

Implementation Reference

• src/index.ts:992-1011 (handler)

  The main handler function for the 'stop_time_entry' tool. It sends a PATCH request to the Clockify API to set the end time on the current running time entry for the specified user in the workspace, using the provided end time or current time if not specified. Returns a success message with the end time and duration.
  private async stopTimeEntry(args: any) { const { workspaceId, userId, end } = args; const endTime = end || new Date().toISOString(); const result = await this.makeRequest( `/workspaces/${workspaceId}/user/${userId}/time-entries`, "PATCH" as "PATCH", { end: endTime } ); return { content: [ { type: "text", text: `Time entry stopped at ${endTime}\nDuration: ${result.timeInterval.duration}`, }, ], isError: false, }; }
• src/index.ts:743-745 (registration)

  The dispatch case in the CallToolRequestSchema handler that routes calls to the stopTimeEntry method, with parameter validation.
  case "stop_time_entry": if (!args?.workspaceId || !args?.userId) throw new McpError(ErrorCode.InvalidParams, 'workspaceId and userId are required'); return await this.stopTimeEntry(args as any);
• src/index.ts:357-368 (schema)

  The tool schema definition including name, description, and input schema, registered in the listTools response.
  name: "stop_time_entry", description: "Stop a running time entry", inputSchema: { type: "object", properties: { workspaceId: { type: "string", description: "Workspace ID" }, userId: { type: "string", description: "User ID" }, end: { type: "string", description: "End time (ISO 8601 format, optional - defaults to now)" }, }, required: ["workspaceId", "userId"], }, },
• src/index.ts:250-713 (registration)

  The overall tool registration in setupToolHandlers where stop_time_entry is listed among all tools for ListToolsRequestSchema.
  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [ // User & Workspace Management { name: "get_current_user", description: "Get information about the current user", inputSchema: { type: "object", properties: {}, }, }, { name: "get_workspaces", description: "Get all workspaces for the current user", inputSchema: { type: "object", properties: {}, }, }, { name: "get_workspace_users", description: "Get all users in a workspace", inputSchema: { type: "object", properties: { workspaceId: { type: "string", description: "Workspace ID" }, }, required: ["workspaceId"], }, }, // 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"], }, }, { 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"], }, }, { name: "delete_time_entry", description: "Delete a time entry", inputSchema: { type: "object", properties: { workspaceId: { type: "string", description: "Workspace ID" }, timeEntryId: { type: "string", description: "Time entry ID" }, }, required: ["workspaceId", "timeEntryId"], }, }, { name: "stop_time_entry", description: "Stop a running time entry", inputSchema: { type: "object", properties: { workspaceId: { type: "string", description: "Workspace ID" }, userId: { type: "string", description: "User ID" }, end: { type: "string", description: "End time (ISO 8601 format, optional - defaults to now)" }, }, required: ["workspaceId", "userId"], }, }, { name: "duplicate_time_entry", description: "Duplicate a time entry", inputSchema: { type: "object", properties: { workspaceId: { type: "string", description: "Workspace ID" }, userId: { type: "string", description: "User ID" }, id: { type: "string", description: "Time entry ID to duplicate" }, }, required: ["workspaceId", "userId", "id"], }, }, // Project Management { name: "create_project", description: "Create a new project", inputSchema: { type: "object", properties: { workspaceId: { type: "string", description: "Workspace ID" }, name: { type: "string", description: "Project name" }, clientId: { type: "string", description: "Client ID (optional)" }, isPublic: { type: "boolean", description: "Whether project is public (optional)" }, billable: { type: "boolean", description: "Whether project is billable (optional)" }, color: { type: "string", description: "Project color (hex code, optional)" }, estimate: { type: "object", properties: { estimate: { type: "string", description: "Estimate duration (ISO 8601 duration)" }, type: { type: "string", enum: ["AUTO", "MANUAL"], description: "Estimate type" }, }, description: "Project estimate (optional)", }, }, required: ["workspaceId", "name"], }, }, { name: "get_projects", description: "Get all projects in a workspace", inputSchema: { type: "object", properties: { workspaceId: { type: "string", description: "Workspace ID" }, archived: { type: "boolean", description: "Filter by archived status" }, name: { type: "string", description: "Filter by project name" }, clientIds: { type: "string", description: "Filter by client IDs (comma-separated)" }, containsClient: { type: "boolean", description: "Filter projects that have clients" }, clientStatus: { type: "string", enum: ["ACTIVE", "ARCHIVED"], description: "Filter by client status" }, users: { type: "string", description: "Filter by user IDs (comma-separated)" }, isTemplate: { type: "boolean", description: "Filter by template status" }, sortColumn: { type: "string", description: "Sort column" }, 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: 5000)" }, }, required: ["workspaceId"], }, }, { name: "get_project", description: "Get a specific project by ID", inputSchema: { type: "object", properties: { workspaceId: { type: "string", description: "Workspace ID" }, projectId: { type: "string", description: "Project ID" }, }, required: ["workspaceId", "projectId"], }, }, { name: "update_project", description: "Update an existing project", inputSchema: { type: "object", properties: { workspaceId: { type: "string", description: "Workspace ID" }, projectId: { type: "string", description: "Project ID" }, name: { type: "string", description: "Project name" }, clientId: { type: "string", description: "Client ID" }, isPublic: { type: "boolean", description: "Whether project is public" }, billable: { type: "boolean", description: "Whether project is billable" }, color: { type: "string", description: "Project color (hex code)" }, archived: { type: "boolean", description: "Whether project is archived" }, }, required: ["workspaceId", "projectId"], }, }, { name: "delete_project", description: "Delete a project", inputSchema: { type: "object", properties: { workspaceId: { type: "string", description: "Workspace ID" }, projectId: { type: "string", description: "Project ID" }, }, required: ["workspaceId", "projectId"], }, }, // Task Management { name: "create_task", description: "Create a new task in a project", inputSchema: { type: "object", properties: { workspaceId: { type: "string", description: "Workspace ID" }, projectId: { type: "string", description: "Project ID" }, name: { type: "string", description: "Task name" }, assigneeIds: { type: "array", items: { type: "string" }, description: "Array of assignee user IDs (optional)" }, estimate: { type: "string", description: "Task estimate (ISO 8601 duration, optional)" }, status: { type: "string", enum: ["ACTIVE", "DONE"], description: "Task status (optional)" }, }, required: ["workspaceId", "projectId", "name"], }, }, { name: "get_tasks", description: "Get all tasks in a project", inputSchema: { type: "object", properties: { workspaceId: { type: "string", description: "Workspace ID" }, projectId: { type: "string", description: "Project ID" }, isActive: { type: "boolean", description: "Filter by active status" }, name: { type: "string", description: "Filter by task name" }, page: { type: "number", description: "Page number (default: 1)" }, pageSize: { type: "number", description: "Page size (default: 50, max: 5000)" }, }, required: ["workspaceId", "projectId"], }, }, { name: "get_task", description: "Get a specific task by ID", inputSchema: { type: "object", properties: { workspaceId: { type: "string", description: "Workspace ID" }, projectId: { type: "string", description: "Project ID" }, taskId: { type: "string", description: "Task ID" }, }, required: ["workspaceId", "projectId", "taskId"], }, }, { name: "update_task", description: "Update an existing task", inputSchema: { type: "object", properties: { workspaceId: { type: "string", description: "Workspace ID" }, projectId: { type: "string", description: "Project ID" }, taskId: { type: "string", description: "Task ID" }, name: { type: "string", description: "Task name" }, assigneeIds: { type: "array", items: { type: "string" }, description: "Array of assignee user IDs" }, estimate: { type: "string", description: "Task estimate (ISO 8601 duration)" }, status: { type: "string", enum: ["ACTIVE", "DONE"], description: "Task status" }, }, required: ["workspaceId", "projectId", "taskId"], }, }, { name: "delete_task", description: "Delete a task", inputSchema: { type: "object", properties: { workspaceId: { type: "string", description: "Workspace ID" }, projectId: { type: "string", description: "Project ID" }, taskId: { type: "string", description: "Task ID" }, }, required: ["workspaceId", "projectId", "taskId"], }, }, // Client Management { name: "create_client", description: "Create a new client", inputSchema: { type: "object", properties: { workspaceId: { type: "string", description: "Workspace ID" }, name: { type: "string", description: "Client name" }, archived: { type: "boolean", description: "Whether client is archived (optional)" }, }, required: ["workspaceId", "name"], }, }, { name: "get_clients", description: "Get all clients in a workspace", inputSchema: { type: "object", properties: { workspaceId: { type: "string", description: "Workspace ID" }, archived: { type: "boolean", description: "Filter by archived status" }, name: { type: "string", description: "Filter by client name" }, page: { type: "number", description: "Page number (default: 1)" }, pageSize: { type: "number", description: "Page size (default: 50, max: 5000)" }, }, required: ["workspaceId"], }, }, { name: "update_client", description: "Update an existing client", inputSchema: { type: "object", properties: { workspaceId: { type: "string", description: "Workspace ID" }, clientId: { type: "string", description: "Client ID" }, name: { type: "string", description: "Client name" }, archived: { type: "boolean", description: "Whether client is archived" }, }, required: ["workspaceId", "clientId"], }, }, { name: "delete_client", description: "Delete a client", inputSchema: { type: "object", properties: { workspaceId: { type: "string", description: "Workspace ID" }, clientId: { type: "string", description: "Client ID" }, }, required: ["workspaceId", "clientId"], }, }, // Tag Management { name: "create_tag", description: "Create a new tag", inputSchema: { type: "object", properties: { workspaceId: { type: "string", description: "Workspace ID" }, name: { type: "string", description: "Tag name" }, archived: { type: "boolean", description: "Whether tag is archived (optional)" }, }, required: ["workspaceId", "name"], }, }, { name: "get_tags", description: "Get all tags in a workspace", inputSchema: { type: "object", properties: { workspaceId: { type: "string", description: "Workspace ID" }, archived: { type: "boolean", description: "Filter by archived status" }, name: { type: "string", description: "Filter by tag name" }, page: { type: "number", description: "Page number (default: 1)" }, pageSize: { type: "number", description: "Page size (default: 50, max: 5000)" }, }, required: ["workspaceId"], }, }, { name: "update_tag", description: "Update an existing tag", inputSchema: { type: "object", properties: { workspaceId: { type: "string", description: "Workspace ID" }, tagId: { type: "string", description: "Tag ID" }, name: { type: "string", description: "Tag name" }, archived: { type: "boolean", description: "Whether tag is archived" }, }, required: ["workspaceId", "tagId"], }, }, { name: "delete_tag", description: "Delete a tag", inputSchema: { type: "object", properties: { workspaceId: { type: "string", description: "Workspace ID" }, tagId: { type: "string", description: "Tag ID" }, }, required: ["workspaceId", "tagId"], }, }, // Reports { 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"], }, }, { name: "get_summary_report", description: "Generate a summary 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" }, groups: { type: "array", items: { type: "string" }, description: "Group by fields (USER, PROJECT, CLIENT, etc.)" }, sortColumn: { type: "string", description: "Sort column" }, sortOrder: { type: "string", enum: ["ASCENDING", "DESCENDING"], description: "Sort order" }, exportType: { type: "string", enum: ["JSON", "PDF", "CSV", "XLSX"], description: "Export format" }, }, required: ["workspaceId", "dateRangeStart", "dateRangeEnd"], }, }, ],