ClickUp MCP Server

Instructions

Implementation Reference

• src/clickup_mcp/tools.py:1052-1068 (handler)

  The handler function that implements the bulk_move_tasks tool logic. It loops through each task_id, resolves the task using _resolve_task_id helper, performs a PUT request to the ClickUp API to update the task's list to target_list_id, and collects results for moved and failed tasks.

  async def bulk_move_tasks(self, task_ids: List[str], target_list_id: str) -> Dict[str, Any]:
      """Move multiple tasks to a different list."""
      results = {"moved": [], "failed": []}
  
      for task_id in task_ids:
          try:
              # Resolve each task ID to get the internal ID
              resolved_task = await self._resolve_task_id(task_id)
              # Moving tasks requires updating the list property
              await self.client._request(
                  "PUT", f"/task/{resolved_task.id}", json={"list": target_list_id}
              )
              results["moved"].append(task_id)
          except Exception as e:
              results["failed"].append({"task_id": task_id, "error": str(e)})
  
      return results

• src/clickup_mcp/tools.py:351-366 (schema)

  Input schema definition for the bulk_move_tasks tool, specifying task_ids as an array of strings and target_list_id as a required string.

  Tool(
      name="bulk_move_tasks",
      description="Move multiple tasks to a different list",
      inputSchema={
          "type": "object",
          "properties": {
              "task_ids": {
                  "type": "array",
                  "items": {"type": "string"},
                  "description": "List of task IDs to move",
              },
              "target_list_id": {"type": "string", "description": "Target list ID"},
          },
          "required": ["task_ids", "target_list_id"],
      },
  ),

• src/clickup_mcp/tools.py:22-57 (registration)

  Registration of the bulk_move_tasks tool handler in the ClickUpTools class's _tools dictionary, which maps tool names to their implementation functions for use in call_tool method.

  self.client = client
  self._tools: Dict[str, Callable] = {
      "create_task": self.create_task,
      "get_task": self.get_task,
      "update_task": self.update_task,
      "delete_task": self.delete_task,
      "list_tasks": self.list_tasks,
      "search_tasks": self.search_tasks,
      "get_subtasks": self.get_subtasks,
      "get_task_comments": self.get_task_comments,
      "create_task_comment": self.create_task_comment,
      "get_task_status": self.get_task_status,
      "update_task_status": self.update_task_status,
      "get_assignees": self.get_assignees,
      "assign_task": self.assign_task,
      "list_spaces": self.list_spaces,
      "list_folders": self.list_folders,
      "list_lists": self.list_lists,
      "find_list_by_name": self.find_list_by_name,
      # Bulk operations
      "bulk_update_tasks": self.bulk_update_tasks,
      "bulk_move_tasks": self.bulk_move_tasks,
      # Time tracking
      "get_time_tracked": self.get_time_tracked,
      "log_time": self.log_time,
      # Templates
      "create_task_from_template": self.create_task_from_template,
      "create_task_chain": self.create_task_chain,
      # Analytics
      "get_team_workload": self.get_team_workload,
      "get_task_analytics": self.get_task_analytics,
      # User management
      "list_users": self.list_users,
      "get_current_user": self.get_current_user,
      "find_user_by_name": self.find_user_by_name,
  }

• src/clickup_mcp/server.py:41-45 (registration)

  MCP server registration of tools list endpoint, which returns all tool definitions including bulk_move_tasks schema via ClickUpTools.get_tool_definitions().

  @self.server.list_tools()
  async def list_tools() -> List[Tool]:
      """List all available tools."""
      return self.tools.get_tool_definitions()

• src/clickup_mcp/tools.py:527-567 (helper)

  Helper method _resolve_task_id used by bulk_move_tasks to smartly resolve task IDs (handling custom IDs, URLs, etc.) to internal task objects.

  async def _resolve_task_id(self, task_id: str, include_subtasks: bool = False) -> Task:
      """Smart task ID resolution that handles both internal and custom IDs."""
      # Parse task ID to determine if it might be a custom ID
      parsed_id, custom_type = parse_task_id(task_id, self.client.config.id_patterns)
  
      # Try direct lookup first (works for both internal and custom IDs)
      try:
          return await self.client.get_task(parsed_id, include_subtasks=include_subtasks)
      except ClickUpAPIError as direct_error:
          # If it might be a custom ID, try with custom_task_ids=true
          if custom_type or "-" in parsed_id:
              try:
                  team_id = (
                      self.client.config.default_team_id
                      or self.client.config.default_workspace_id
                  )
                  return await self.client.get_task(
                      parsed_id,
                      include_subtasks=include_subtasks,
                      custom_task_ids=True,
                      team_id=team_id,
                  )
              except ClickUpAPIError as custom_error:
                  # If both fail, try search as final fallback
                  try:
                      tasks = await self.client.search_tasks(query=task_id)
                      if not tasks:
                          raise ClickUpAPIError(f"Task '{task_id}' not found")
  
                      # Find exact match by custom_id or use first result
                      for task in tasks:
                          if hasattr(task, "custom_id") and task.custom_id == task_id:
                              return task
                      return tasks[0]
                  except ClickUpAPIError:
                      # Re-raise the most relevant error
                      raise (custom_error if custom_type else direct_error) from None
          else:
              # Not a custom ID pattern, re-raise the original error
              raise direct_error