Clockify MCP Server

Instructions

Implementation Reference

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

  The handler function for the 'get_tasks' tool. It extracts workspaceId and projectId from arguments, builds query parameters for optional filters, calls the Clockify API endpoint `/workspaces/{workspaceId}/projects/{projectId}/tasks`, retrieves the tasks, and returns a formatted text response listing the tasks with their names, IDs, status, and estimates.

  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)

  The tool registration in the list of tools returned by ListToolsRequestSchema, including the name 'get_tasks', description, and input schema defining required workspaceId and projectId, with optional filters.

  {
    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)

  The dispatch case in the CallToolRequestSchema handler that validates required parameters and calls the getTasks method for the 'get_tasks' tool.

  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 codebase, matching the expected API response.

  interface Task {
    id?: string;
    name: string;
    projectId: string;
    assigneeIds?: string[];
    estimate?: string;
    status?: "ACTIVE" | "DONE";
  }