ClickUp MCP Server

Instructions

Implementation Reference

• src/tools/list.ts:274-349 (handler)

  The primary handler function for the 'create_list_in_folder' tool. It validates inputs, resolves folder IDs using workspace service if names are provided, prepares list data, calls the list service to create the list in the folder, and returns a formatted response with the new list details.
  export async function handleCreateListInFolder(parameters: any) { const { name, folderId, folderName, spaceId, spaceName, content, status } = parameters; // Validate required fields if (!name) { throw new Error("List name is required"); } let targetFolderId = folderId; // If no folderId but folderName is provided, look up the folder ID if (!targetFolderId && folderName) { let targetSpaceId = spaceId; // If no spaceId provided but spaceName is, look up the space ID first if (!targetSpaceId && spaceName) { const spaceIdResult = await workspaceService.findSpaceByName(spaceName); if (!spaceIdResult) { throw new Error(`Space "${spaceName}" not found`); } targetSpaceId = spaceIdResult.id; } if (!targetSpaceId) { throw new Error("When using folderName to identify a folder, you must also provide either spaceId or spaceName to locate the correct folder. This is because folder names might not be unique across different spaces."); } // Find the folder in the workspace hierarchy const hierarchy = await workspaceService.getWorkspaceHierarchy(); const folderInfo = workspaceService.findIDByNameInHierarchy(hierarchy, folderName, 'folder'); if (!folderInfo) { throw new Error(`Folder "${folderName}" not found in space`); } targetFolderId = folderInfo.id; } if (!targetFolderId) { throw new Error("Either folderId or folderName must be provided"); } // Prepare list data const listData: CreateListData = { name }; // Add optional fields if provided if (content) listData.content = content; if (status) listData.status = status; try { // Create the list in the folder const newList = await listService.createListInFolder(targetFolderId, listData); return { content: [{ type: "text", text: JSON.stringify( { id: newList.id, name: newList.name, content: newList.content, space: { id: newList.space.id, name: newList.space.name }, message: `List "${newList.name}" created successfully in folder` }, null, 2 ) }] }; } catch (error: any) { throw new Error(`Failed to create list in folder: ${error.message}`); } }
• src/tools/list.ts:74-111 (schema)

  The tool definition object defining the 'create_list_in_folder' tool, including its name, description, and detailed inputSchema for parameter validation.
  export const createListInFolderTool = { name: "create_list_in_folder", description: "Create a new list within a ClickUp folder. You MUST provide either: 1) folderId alone, or 2) folderName WITH either spaceName or spaceId. Folder names may not be unique across spaces, which is why space information is required when using folderName.", inputSchema: { type: "object", properties: { name: { type: "string", description: "Name of the list" }, folderId: { type: "string", description: "ID of the folder to create the list in. If you have this, you don't need folderName or space information." }, folderName: { type: "string", description: "Name of the folder to create the list in. When using this, you MUST also provide either spaceName or spaceId." }, spaceId: { type: "string", description: "ID of the space containing the folder. Required when using folderName instead of folderId." }, spaceName: { type: "string", description: "Name of the space containing the folder. Required when using folderName instead of folderId." }, content: { type: "string", description: "Description or content of the list" }, status: { type: "string", description: "Status of the list (uses folder default if not specified)" } }, required: ["name"] } };
• src/server.ts:67-93 (registration)

  Registration of the createListInFolderTool in the list of available tools returned by the ListToolsRequestSchema handler (line 83 specifically includes createListInFolderTool).
  server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ workspaceHierarchyTool, createTaskTool, getTaskTool, getTasksTool, updateTaskTool, moveTaskTool, duplicateTaskTool, deleteTaskTool, createBulkTasksTool, updateBulkTasksTool, moveBulkTasksTool, deleteBulkTasksTool, createListTool, createListInFolderTool, getListTool, updateListTool, deleteListTool, createFolderTool, getFolderTool, updateFolderTool, deleteFolderTool ] }; });
• src/server.ts:125-127 (registration)

  Dispatch/registration of the handler for 'create_list_in_folder' in the CallToolRequestSchema switch statement.
  return handleCreateList(params); case "create_list_in_folder": return handleCreateListInFolder(params);
• src/services/clickup/list.ts:75-89 (helper)

  The underlying service method called by the handler to perform the actual ClickUp API call for creating a list in a folder.
  async createListInFolder(folderId: string, listData: CreateListData): Promise<ClickUpList> { this.logOperation('createListInFolder', { folderId, ...listData }); try { return await this.makeRequest(async () => { const response = await this.client.post<ClickUpList>( `/folder/${folderId}/list`, listData ); return response.data; }); } catch (error) { throw this.handleError(error, `Failed to create list in folder ${folderId}`); } }