Clockify MCP Server

Instructions

Implementation Reference

• src/index.ts:1154-1181 (handler)

  The main handler function that fetches tasks from the Clockify API for a given workspace and project. It constructs query parameters from the input arguments, makes the API request to /workspaces/{workspaceId}/projects/{projectId}/tasks, and returns a formatted text response listing the tasks.
  private async getTasks(args: any) { const { workspaceId, projectId, ...params } = args; const queryParams = new URLSearchParams(); Object.entries(params).forEach(([key, value]) => { if (value !== undefined && value !== null) { queryParams.append(key, String(value)); } }); const endpoint = queryParams.toString() ? `/workspaces/${workspaceId}/projects/${projectId}/tasks?${queryParams.toString()}` : `/workspaces/${workspaceId}/projects/${projectId}/tasks`; const tasks = await this.makeRequest(endpoint); return { content: [ { type: "text", text: `Found ${tasks.length} task(s):\n${tasks .map((t: any) => `- ${t.name} (${t.id}) | Status: ${t.status} | Estimate: ${t.estimate || "None"}`) .join("\n")}`, }, ], isError: false, }; }
• src/index.ts:490-505 (registration)

  Registration of the 'get_tasks' tool in the server's listTools response, including its name, description, and input schema definition.
  { 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"], }, },
• src/index.ts:771-773 (registration)

  Dispatch logic in the central CallToolRequest handler that validates required parameters (workspaceId, projectId) and invokes the getTasks handler method.
  case "get_tasks": if (!args?.workspaceId || !args?.projectId) throw new McpError(ErrorCode.InvalidParams, 'workspaceId and projectId are required'); return await this.getTasks(args as any);
• src/index.ts:42-49 (schema)

  TypeScript interface defining the structure of a Task object, used in the tool's responses and API interactions.
  interface Task { id?: string; name: string; projectId: string; assigneeIds?: string[]; estimate?: string; status?: "ACTIVE" | "DONE"; }
• src/index.ts:203-247 (helper)

  Utility method used by getTasks to make authenticated HTTP requests to the Clockify API, handling errors and JSON parsing.
  private async makeRequest( endpoint: string, method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" = "GET", data?: any, baseUrl?: string ): Promise<any> { if (!this.config.apiKey) { throw new McpError( ErrorCode.InvalidParams, "Clockify API key not configured. Set CLOCKIFY_API_KEY environment variable." ); } const url = `${baseUrl || this.config.baseUrl}${endpoint}`; const headers: Record<string, string> = { "X-Api-Key": this.config.apiKey, "Content-Type": "application/json", }; try { const response = await fetch(url, { method, headers, body: data ? JSON.stringify(data) : undefined, }); if (!response.ok) { const errorText = await response.text(); throw new McpError( ErrorCode.InternalError, `Clockify API error (${response.status}): ${errorText}` ); } return response.json(); } catch (error) { if (error instanceof McpError) { throw error; } throw new McpError( ErrorCode.InternalError, `Request failed: ${error instanceof Error ? error.message : String(error)}` ); } }