create_folder
Organize ClickUp lists by creating folders within spaces to group related content together for better project management.
Instructions
Create a new folder in a ClickUp space for organizing related lists. You MUST provide:
A folder name
Either spaceId (preferred) or spaceName
After creating a folder, you can add lists to it using create_list_in_folder.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the folder | |
| spaceId | No | ID of the space to create the folder in (preferred). Use this instead of spaceName if you have it. | |
| spaceName | No | Name of the space to create the folder in. Only use if you don't have spaceId. | |
| override_statuses | No | Whether to override space statuses with folder-specific statuses |
Implementation Reference
- src/tools/folder.ts:156-212 (handler)Main handler function for the create_folder tool. Validates input parameters, resolves space ID using workspace service if spaceName provided, prepares folder data, calls folderService.createFolder, and returns formatted JSON response with the new folder details.export async function handleCreateFolder(parameters: any) { const { name, spaceId, spaceName, override_statuses } = parameters; // Validate required fields if (!name) { throw new Error("Folder name is required"); } let targetSpaceId = spaceId; // If no spaceId but spaceName is provided, look up the space ID 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("Either spaceId or spaceName must be provided"); } // Prepare folder data const folderData: CreateFolderData = { name }; // Add optional fields if provided if (override_statuses !== undefined) folderData.override_statuses = override_statuses; try { // Create the folder const newFolder = await folderService.createFolder(targetSpaceId, folderData); return { content: [{ type: "text", text: JSON.stringify( { id: newFolder.id, name: newFolder.name, space: { id: newFolder.space.id, name: newFolder.space.name }, message: `Folder "${newFolder.name}" created successfully` }, null, 2 ) }] }; } catch (error: any) { throw new Error(`Failed to create folder: ${error.message}`); } }
- src/tools/folder.ts:27-52 (schema)Tool schema definition including name, description, and inputSchema for parameter validation in MCP protocol.export const createFolderTool = { name: "create_folder", description: "Create a new folder in a ClickUp space for organizing related lists. You MUST provide:\n1. A folder name\n2. Either spaceId (preferred) or spaceName\n\nAfter creating a folder, you can add lists to it using create_list_in_folder.", inputSchema: { type: "object", properties: { name: { type: "string", description: "Name of the folder" }, spaceId: { type: "string", description: "ID of the space to create the folder in (preferred). Use this instead of spaceName if you have it." }, spaceName: { type: "string", description: "Name of the space to create the folder in. Only use if you don't have spaceId." }, override_statuses: { type: "boolean", description: "Whether to override space statuses with folder-specific statuses" } }, required: ["name"] } };
- src/server.ts:134-135 (registration)Registration of the create_folder tool handler in the CallToolRequestHandler switch statement.case "create_folder": return handleCreateFolder(params);
- src/server.ts:87-87 (registration)Registration of the createFolderTool definition in the ListToolsRequestHandler tool list.createFolderTool,
- src/services/clickup/folder.ts:64-77 (helper)Underlying service method called by the handler to perform the actual ClickUp API call for creating a folder.async createFolder(spaceId: string, folderData: CreateFolderData): Promise<ClickUpFolder> { try { this.logOperation('createFolder', { spaceId, ...folderData }); const response = await this.client.post<ClickUpFolder>( `/space/${spaceId}/folder`, folderData ); return response.data; } catch (error) { throw this.handleError(error, `Failed to create folder in space ${spaceId}`); } }