ClickUp MCP Server

Instructions

Implementation Reference

• src/tools/folder.ts:218-279 (handler)

  Handler function that executes the get_folder tool: resolves folderId from name if needed, fetches folder details via folderService.getFolder, and returns formatted JSON response.
  export async function handleGetFolder(parameters: any) { const { folderId, folderName, spaceId, spaceName } = parameters; let targetFolderId = folderId; // If no folderId provided but folderName is, 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("Either spaceId or spaceName must be provided when using folderName"); } const folderResult = await folderService.findFolderByName(targetSpaceId, folderName); if (!folderResult) { throw new Error(`Folder "${folderName}" not found in space`); } targetFolderId = folderResult.id; } if (!targetFolderId) { throw new Error("Either folderId or folderName must be provided"); } try { // Get the folder const folder = await folderService.getFolder(targetFolderId); return { content: [{ type: "text", text: JSON.stringify( { id: folder.id, name: folder.name, lists: folder.lists.map((list: any) => ({ id: list.id, name: list.name })), space: { id: folder.space.id, name: folder.space.name } }, null, 2 ) }] }; } catch (error: any) { throw new Error(`Failed to retrieve folder: ${error.message}`); } }
• src/tools/folder.ts:57-82 (schema)

  Tool definition including name, description, and inputSchema for validating get_folder parameters.
  export const getFolderTool = { name: "get_folder", description: "Retrieve details about a specific folder including name, status, and metadata. Valid parameter combinations:\n1. Use folderId alone (preferred)\n2. Use folderName + (spaceId or spaceName)\n\nHelps you understand folder structure before creating or updating lists.", inputSchema: { type: "object", properties: { folderId: { type: "string", description: "ID of folder to retrieve (preferred). Use this instead of folderName if you have it." }, folderName: { type: "string", description: "Name of folder to retrieve. When using this, you MUST also provide spaceId or spaceName." }, spaceId: { type: "string", description: "ID of space containing the folder (required with folderName). Use this instead of spaceName if you have it." }, spaceName: { type: "string", description: "Name of space containing the folder (required with folderName). Only use if you don't have spaceId." } }, required: [] } };
• src/server.ts:67-93 (registration)

  Registration of getFolderTool in the list of available tools returned by ListToolsRequest.
  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:136-137 (registration)

  Registration in CallToolRequest switch statement that routes 'get_folder' calls to handleGetFolder.
  case "get_folder": return handleGetFolder(params);
• src/services/clickup/folder.ts:84-96 (helper)

  FolderService.getFolder helper method called by the handler to fetch folder data from ClickUp API.
  async getFolder(folderId: string): Promise<ClickUpFolder> { try { this.logOperation('getFolder', { folderId }); const response = await this.client.get<ClickUpFolder>( `/folder/${folderId}` ); return response.data; } catch (error) { throw this.handleError(error, `Failed to get folder ${folderId}`); } }