get_list
Retrieve details about a specific ClickUp list using either the list ID or list name to access task organization information.
Instructions
Retrieve details about a specific ClickUp list. You MUST provide either listId or listName. Using listId is more reliable as list names might not be unique.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| listId | No | ID of the list to retrieve. Use this instead of listName if you have the ID. | |
| listName | No | Name of the list to retrieve. May be ambiguous if multiple lists have the same name. |
Implementation Reference
- src/tools/list.ts:355-400 (handler)Handler function that resolves the list ID if only name is provided, fetches the list details using listService.getList, and returns formatted JSON response with list info including URL.export async function handleGetList(parameters: any) { const { listId, listName } = parameters; let targetListId = listId; // If no listId provided but listName is, look up the list ID if (!targetListId && listName) { const listResult = await findListIDByName(workspaceService, listName); if (!listResult) { throw new Error(`List "${listName}" not found`); } targetListId = listResult.id; } if (!targetListId) { throw new Error("Either listId or listName must be provided"); } try { // Get the list const list = await listService.getList(targetListId); return { content: [{ type: "text", text: JSON.stringify( { id: list.id, name: list.name, content: list.content, space: { id: list.space.id, name: list.space.name }, status: list.status, url: `https://app.clickup.com/${config.clickupTeamId}/v/l/${list.id}` }, null, 2 ) }] }; } catch (error: any) { throw new Error(`Failed to retrieve list: ${error.message}`); } }
- src/tools/list.ts:116-133 (schema)Tool definition including the name, description, and inputSchema for validating parameters: listId or listName.export const getListTool = { name: "get_list", description: "Retrieve details about a specific ClickUp list. You MUST provide either listId or listName. Using listId is more reliable as list names might not be unique.", inputSchema: { type: "object", properties: { listId: { type: "string", description: "ID of the list to retrieve. Use this instead of listName if you have the ID." }, listName: { type: "string", description: "Name of the list to retrieve. May be ambiguous if multiple lists have the same name." } }, required: [] } };
- src/server.ts:67-93 (registration)Registration of the get_list tool (as getListTool) in the list of available tools returned by the ListToolsRequest handler.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:128-129 (registration)Switch case in CallToolRequest handler that routes 'get_list' calls to the handleGetList function.case "get_list": return handleGetList(params);
- src/tools/list.ts:195-201 (helper)Helper function to resolve a list name to its ID by searching the workspace hierarchy, used when only listName is provided.export async function findListIDByName(workspaceService: any, listName: string): Promise<{ id: string; name: string } | null> { // Use workspace service to find the list in the hierarchy const hierarchy = await workspaceService.getWorkspaceHierarchy(); const listInfo = workspaceService.findIDByNameInHierarchy(hierarchy, listName, 'list'); if (!listInfo) return null; return { id: listInfo.id, name: listName }; }