Clockify MCP

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

• src/handlers.ts:201-228 (handler)

  Executes the addTimeEntry tool by validating required parameters (projectId, description, start, end), constructing the time entry body, and POSTing it to the Clockify API endpoint /workspaces/{workspaceId}/time-entries using the clockifyFetch helper.
  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)

  Defines the tool metadata including name, description, and input schema (with required fields: projectId, description, start, end as strings) for addTimeEntry, returned in listToolsHandler.
  { 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/handlers.ts:13-32 (helper)

  Reusable helper to perform authenticated fetch requests to Clockify API, handles API key, base URL, headers, error handling, and JSON response parsing. Directly used in addTimeEntry handler.
  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 to retrieve the Clockify API key from environment variable CLOCKIFY_API_KEY, throws error if missing. 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; }
• src/index.ts:43-49 (registration)

  Registers the general tool handlers: listToolsHandler for listing tools (including addTimeEntry schema) and callToolHandler for executing tools (including addTimeEntry logic).
  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/index.ts:19-19 (registration)

  Imports the handlers containing addTimeEntry logic and schema from handlers.ts.
  import { listToolsHandler, callToolHandler } from "./handlers.js";