create_task

Instructions

Implementation Reference

• src/tools/task.ts:1078-1138 (handler)

  The primary handler function for the 'create_task' tool, dispatched by the MCP server. It validates inputs, resolves list ID if using listName, constructs CreateTaskData, calls the ClickUp task service to create the task, and returns a formatted MCP content response.

  export async function handleCreateTask(parameters: any) {
    const { name, description, markdown_description, listId, listName, status, priority, dueDate } = parameters;
    
    // Validate required fields
    if (!name) {
      throw new Error("Task name is required");
    }
    
    let targetListId = listId;
    
    // If no listId but listName is provided, look up the list ID
    if (!targetListId && listName) {
      // Use workspace service to find the list by name in the hierarchy
      const hierarchy = await workspaceService.getWorkspaceHierarchy();
      const listInfo = workspaceService.findIDByNameInHierarchy(hierarchy, listName, 'list');
      
      if (!listInfo) {
        throw new Error(`List "${listName}" not found`);
      }
      targetListId = listInfo.id;
    }
    
    if (!targetListId) {
      throw new Error("Either listId or listName must be provided");
    }
  
    // Prepare task data
    const taskData: CreateTaskData = {
      name,
      description,
      markdown_description,
      status,
      priority: priority as TaskPriority,
      due_date: dueDate ? parseDueDate(dueDate) : undefined
    };
  
    // Add due_date_time flag if due date is set
    if (dueDate && taskData.due_date) {
      taskData.due_date_time = true;
    }
  
    // Create the task
    const task = await taskService.createTask(targetListId, taskData);
  
    // Format response
    return {
      content: [{
        type: "text",
        text: JSON.stringify({
          id: task.id,
          name: task.name,
          url: task.url,
          status: task.status?.status || "New",
          due_date: task.due_date ? formatDueDate(Number(task.due_date)) : undefined,
          list: task.list.name,
          space: task.space.name,
          folder: task.folder?.name
        }, null, 2)
      }]
    };
  }

• src/tools/task.ts:38-75 (schema)

  The input JSON Schema for the create_task tool, defining parameters like name (required), description, listId/listName, status, priority, dueDate.

  inputSchema: {
    type: "object",
    properties: {
      name: {
        type: "string",
        description: "Name of the task. Put a relevant emoji followed by a blank space before the name."
      },
      description: {
        type: "string",
        description: "Plain text description for the task"
      },
      markdown_description: {
        type: "string",
        description: "Markdown formatted description for the task. If provided, this takes precedence over description"
      },
      listId: {
        type: "string",
        description: "ID of the list to create the task in (optional if using listName instead). If you have this ID from a previous response, use it directly rather than looking up by name."
      },
      listName: {
        type: "string",
        description: "Name of the list to create the task in - will automatically find the list by name (optional if using listId instead). Only use this if you don't already have the list ID from previous responses."
      },
      status: {
        type: "string",
        description: "OPTIONAL: Override the default ClickUp status. In most cases, you should omit this to use ClickUp defaults"
      },
      priority: {
        type: "number",
        description: "Priority of the task (1-4), where 1 is urgent/highest priority and 4 is lowest priority. Only set this when the user explicitly requests a priority level."
      },
      dueDate: {
        type: "string",
        description: "Due date of the task (Unix timestamp in milliseconds). Convert dates to this format before submitting."
      }
    },
    required: ["name"]
  },

• src/server.ts:102-103 (registration)

  Dispatch registration in the MCP server's CallToolRequestSchema handler: routes 'create_task' calls to handleCreateTask.

  case "create_task":
    return handleCreateTask(params);

• src/server.ts:67-93 (registration)

  Tool registration in ListToolsRequestSchema handler: includes createTaskTool in the list of available tools.

  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/services/clickup/task.ts:68-120 (helper)

  The underlying ClickUp service method taskService.createTask called by the handler to perform the actual task creation API call.

  async createTask(listId: string, taskData: CreateTaskData): Promise<ClickUpTask> {
    this.logOperation('createTask', { listId, ...taskData });
    
    try {
      return await this.makeRequest(async () => {
        const response = await this.client.post<ClickUpTask>(
          `/list/${listId}/task`,
          taskData
        );
        return response.data;
      });
    } catch (error) {
      throw this.handleError(error, `Failed to create task in list ${listId}`);
    }
  }
  
  /**
   * Get all tasks in a list with optional filtering
   * @param listId The ID of the list to get tasks from
   * @param filters Optional filters to apply
   * @returns List of tasks matching the filters
   */
  async getTasks(listId: string, filters: TaskFilters = {}): Promise<ClickUpTask[]> {
    this.logOperation('getTasks', { listId, filters });
    
    try {
      return await this.makeRequest(async () => {
        const params = new URLSearchParams();
        
        // Add all filters to the query parameters
        if (filters.include_closed) params.append('include_closed', String(filters.include_closed));
        if (filters.subtasks) params.append('subtasks', String(filters.subtasks));
        if (filters.page) params.append('page', String(filters.page));
        if (filters.order_by) params.append('order_by', filters.order_by);
        if (filters.reverse) params.append('reverse', String(filters.reverse));
        if (filters.statuses && filters.statuses.length > 0) {
          filters.statuses.forEach(status => params.append('statuses[]', status));
        }
        if (filters.assignees && filters.assignees.length > 0) {
          filters.assignees.forEach(assignee => params.append('assignees[]', assignee));
        }
        if (filters.due_date_gt) params.append('due_date_gt', String(filters.due_date_gt));
        if (filters.due_date_lt) params.append('due_date_lt', String(filters.due_date_lt));
        if (filters.date_created_gt) params.append('date_created_gt', String(filters.date_created_gt));
        if (filters.date_created_lt) params.append('date_created_lt', String(filters.date_created_lt));
        if (filters.date_updated_gt) params.append('date_updated_gt', String(filters.date_updated_gt));
        if (filters.date_updated_lt) params.append('date_updated_lt', String(filters.date_updated_lt));
        
        // Handle custom fields if present
        if (filters.custom_fields) {
          Object.entries(filters.custom_fields).forEach(([key, value]) => {
            params.append(`custom_fields[${key}]`, String(value));
          });

• src/services/clickup/types.ts:201-248 (schema)

  TypeScript interface CreateTaskData used to type the task data payload sent to ClickUp API.

  export interface CreateTaskData {
    name: string;
    description?: string;
    markdown_description?: string;
    assignees?: (number | string)[];
    tags?: string[];
    status?: string;
    priority?: TaskPriority;
    due_date?: number;
    due_date_time?: boolean;
    time_estimate?: number;
    start_date?: number;
    start_date_time?: boolean;
    notify_all?: boolean;
    parent?: string | null;
    links_to?: string | null;
    check_required_custom_fields?: boolean;
    custom_fields?: Array<{
      id: string;
      value: any;
    }>;
  }
  
  /**
   * Data for creating a list
   */
  export interface CreateListData {
    name: string;
    content?: string;
    due_date?: number;
    due_date_time?: boolean;
    priority?: TaskPriority;
    assignee?: number;
    status?: string;
  }
  
  /**
   * Data for creating a folder
   */
  export interface CreateFolderData {
    name: string;
    override_statuses?: boolean;
  }
  
  /**
   * Update task data (partial)
   */
  export interface UpdateTaskData extends Partial<CreateTaskData> {}