addTimeEntry
Log work hours to a Clockify project by specifying start time, end time, and task description for accurate time tracking.
Instructions
Add a time entry to a project.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| projectId | Yes | Clockify project ID | |
| description | Yes | Description of the time entry | |
| start | Yes | Start time (ISO8601) | |
| end | Yes | End time (ISO8601) |
Implementation Reference
- src/handlers.ts:201-228 (handler)The switch case implementing the 'addTimeEntry' tool handler. Validates input parameters (projectId, description, start, end), constructs the time entry body, and POSTs it to the Clockify API endpoint for the user's workspace.
case "addTimeEntry": { const { projectId, description, start, end } = request.params.arguments || {}; if (!projectId || !description || !start || !end) { throw new Error("projectId, description, start, and end are required"); } const body = { start, end, description, projectId, }; const entry = await clockifyFetch( `/workspaces/${workspaceId}/time-entries`, { method: "POST", body: JSON.stringify(body), }, ); return { content: [ { type: "text", text: JSON.stringify(entry, null, 2), }, ], }; } - src/handlers.ts:62-78 (schema)The tool definition in listToolsHandler, including name, description, and inputSchema for 'addTimeEntry'.
{ name: "addTimeEntry", description: "Add a time entry to a project.", inputSchema: { type: "object", properties: { projectId: { type: "string", description: "Clockify project ID" }, description: { type: "string", description: "Description of the time entry", }, start: { type: "string", description: "Start time (ISO8601)" }, end: { type: "string", description: "End time (ISO8601)" }, }, required: ["projectId", "description", "start", "end"], }, }, - src/index.ts:43-49 (registration)Registers the request handlers for listing tools (listToolsHandler, which includes addTimeEntry) and calling tools (callToolHandler, which dispatches to addTimeEntry implementation).
server.setRequestHandler(ListToolsRequestSchema, listToolsHandler); /** * Handler for the create_note tool. * Creates a new note with the provided title and content, and returns success message. */ server.setRequestHandler(CallToolRequestSchema, callToolHandler); - src/handlers.ts:13-32 (helper)Helper function clockifyFetch used by the addTimeEntry handler to make authenticated POST request to Clockify API.
async function clockifyFetch(endpoint: string, options: RequestInit = {}) { const apiKey = getApiKey(); const baseUrl = "https://api.clockify.me/api/v1"; const url = endpoint.startsWith("http") ? endpoint : `${baseUrl}${endpoint}`; const headers = { "X-Api-Key": apiKey, "Content-Type": "application/json", ...(options.headers || {}), }; const response = await fetch(url, { ...options, headers }); if (!response.ok) { const text = await response.text(); console.error( `[Error] Clockify API ${url} failed: ${response.status} ${text}`, ); throw new Error(`Clockify API error: ${response.status} ${text}`); } return response.json(); } - src/handlers.ts:4-10 (helper)Helper function to retrieve the Clockify API key from environment, used by clockifyFetch.
function getApiKey(): string { const apiKey = process.env.CLOCKIFY_API_KEY; if (!apiKey) { throw new Error("CLOCKIFY_API_KEY is not set in MCP config."); } return apiKey; }