ClickUp MCP Server

Instructions

Implementation Reference

• src/tools/task.ts:998-1073 (handler)

  Handler function that processes the create_bulk_tasks tool call. Validates input, resolves list ID if needed, maps tasks to ClickUp format, calls taskService.createBulkTasks, and formats results with success/failure counts.
  export async function handleCreateBulkTasks(parameters: any) { // Validate required parameters const { tasks, listId, listName } = parameters; if (!tasks || !Array.isArray(tasks) || tasks.length === 0) { throw new Error('You must provide a non-empty array of tasks to create'); } let targetListId = listId; // If no listId but listName is provided, look up the list ID if (!targetListId && listName) { const listInfo = await findListIDByName(workspaceService, listName); if (!listInfo) { throw new Error(`List "${listName}" not found`); } targetListId = listInfo.id; } if (!targetListId) { throw new Error("Either listId or listName must be provided"); } const results = { total: tasks.length, successful: 0, failed: 0, failures: [] as any[] }; // Map tasks to ClickUp format const clickupTasks = tasks.map((task: any) => { const taskData: CreateTaskData = { name: task.name, description: task.description, markdown_description: task.markdown_description, status: task.status, priority: task.priority as TaskPriority, due_date: task.dueDate ? parseDueDate(task.dueDate) : undefined }; // Add due_date_time flag if due date is set if (task.dueDate && taskData.due_date) { taskData.due_date_time = true; } return taskData; }); // Create tasks in bulk using the task service try { const bulkResult = await taskService.createBulkTasks(targetListId, { tasks: clickupTasks }); // Update results based on bulk operation outcome results.successful = bulkResult.successfulItems.length; results.failed = bulkResult.failedItems.length; results.failures = bulkResult.failedItems.map(failure => ({ task: failure.item.name, error: failure.error.message })); } catch (error: any) { // If the bulk operation itself fails, mark all tasks as failed results.failed = tasks.length; results.failures = tasks.map(task => ({ task: task.name, error: error.message })); } return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] }; }
• src/tools/task.ts:749-822 (schema)

  Tool definition object including name, description, and detailed inputSchema for validating parameters like tasks array, listId/listName, and optional batching options.
  export const createBulkTasksTool = { name: "create_bulk_tasks", description: "Create multiple tasks in a list efficiently. You MUST provide:\n1. An array of tasks with required properties\n2. Either listId or listName to specify the target list\n\nOptional: Configure batch size and concurrency for performance.", inputSchema: { type: "object", properties: { listId: { type: "string", description: "ID of list for new tasks (preferred). Use this instead of listName if you have it." }, listName: { type: "string", description: "Name of list for new tasks. Only use if you don't have listId." }, tasks: { type: "array", description: "Array of tasks to create. Each task must have at least a name.", items: { type: "object", properties: { name: { type: "string", description: "Task name with emoji prefix" }, description: { type: "string", description: "Plain text description" }, markdown_description: { type: "string", description: "Markdown description (overrides plain text)" }, status: { type: "string", description: "Task status (uses list default if omitted)" }, priority: { type: "number", description: "Priority 1-4 (1=urgent, 4=low)" }, dueDate: { type: "string", description: "Due date (Unix timestamp ms)" } }, required: ["name"] } }, options: { type: "object", description: "Optional processing settings", properties: { batchSize: { type: "number", description: "Tasks per batch (default: 10)" }, concurrency: { type: "number", description: "Parallel operations (default: 1)" }, continueOnError: { type: "boolean", description: "Continue if some tasks fail" }, retryCount: { type: "number", description: "Retry attempts for failures" } } } }, required: ["tasks"] } };
• src/server.ts:99-144 (registration)

  Server request handler switch statement that routes 'create_bulk_tasks' calls to handleCreateBulkTasks. Also registers the tool in the ListTools response at line 78.
  switch (name) { case "get_workspace_hierarchy": return handleGetWorkspaceHierarchy(); case "create_task": return handleCreateTask(params); case "update_task": return handleUpdateTask(params); case "move_task": return handleMoveTask(params); case "duplicate_task": return handleDuplicateTask(params); case "get_task": return handleGetTask(params); case "get_tasks": return handleGetTasks(params); case "delete_task": return handleDeleteTask(params); case "create_bulk_tasks": return handleCreateBulkTasks(params); case "update_bulk_tasks": return handleUpdateBulkTasks(params as { tasks: any[] }); case "move_bulk_tasks": return handleMoveBulkTasks(params as { tasks: any[], targetListId?: string, targetListName?: string }); case "delete_bulk_tasks": return handleDeleteBulkTasks(params as { tasks: any[] }); case "create_list": return handleCreateList(params); case "create_list_in_folder": return handleCreateListInFolder(params); case "get_list": return handleGetList(params); case "update_list": return handleUpdateList(params); case "delete_list": return handleDeleteList(params); case "create_folder": return handleCreateFolder(params); case "get_folder": return handleGetFolder(params); case "update_folder": return handleUpdateFolder(params); case "delete_folder": return handleDeleteFolder(params); default: throw new Error(`Unknown tool: ${name}`); }
• src/server.ts:70-91 (registration)

  ListToolsRequestSchema handler that returns array of tools including createBulkTasksTool for MCP tool discovery.
  workspaceHierarchyTool, createTaskTool, getTaskTool, getTasksTool, updateTaskTool, moveTaskTool, duplicateTaskTool, deleteTaskTool, createBulkTasksTool, updateBulkTasksTool, moveBulkTasksTool, deleteBulkTasksTool, createListTool, createListInFolderTool, getListTool, updateListTool, deleteListTool, createFolderTool, getFolderTool, updateFolderTool, deleteFolderTool ]
• src/services/clickup/task.ts:343-428 (helper)

  Core service method in TaskService that implements bulk task creation using BulkProcessor for batching, concurrency, retries, and error handling. Called by the tool handler.
  async createBulkTasks( listId: string, data: { tasks: Array<CreateTaskData> }, options?: BulkOperationOptions, progressCallback?: (progress: ProgressInfo) => void ): Promise<BulkOperationResult<ClickUpTask>> { this.logOperation('createBulkTasks', { listId, taskCount: data.tasks.length, batchSize: options?.batchSize, concurrency: options?.concurrency }); try { // Validate list exists before proceeding const list = await this.listService.getList(listId).catch(() => null); if (!list) { throw new ClickUpServiceError( `List not found with ID: ${listId}`, ErrorCode.NOT_FOUND ); } // Set default options for better performance const bulkOptions: BulkOperationOptions = { batchSize: options?.batchSize ?? 5, // Smaller batch size for better rate limit handling concurrency: options?.concurrency ?? 2, // Lower concurrency to avoid rate limits continueOnError: options?.continueOnError ?? true, // Continue on individual task failures retryCount: options?.retryCount ?? 3, // Retry failed operations ...options }; // Add list validation to progress tracking const wrappedCallback = progressCallback ? (progress: ProgressInfo) => { progress.context = { listId, listName: list.name }; progressCallback(progress); } : undefined; return await this.bulkProcessor.processBulk( data.tasks, async (taskData) => { try { // Ensure task data is properly formatted const sanitizedData = { ...taskData, // Remove any accidentally included list IDs in task data list: undefined, // Ensure name has emoji if missing name: taskData.name.match(/^\p{Emoji}/u) ? taskData.name : '📋 ' + taskData.name }; return await this.createTask(listId, sanitizedData); } catch (error) { // Enhance error context for better debugging if (error instanceof ClickUpServiceError) { error.context = { ...error.context, taskName: taskData.name, listId, listName: list.name }; } throw error; } }, bulkOptions ); } catch (error: any) { const errorMessage = error instanceof ClickUpServiceError ? error.message : `Failed to create tasks in bulk: ${error.message}`; throw new ClickUpServiceError( errorMessage, error instanceof ClickUpServiceError ? error.code : ErrorCode.UNKNOWN, { listId, taskCount: data.tasks.length, error: error instanceof Error ? error.message : String(error) } ); } }