ClickUp MCP Server

Instructions

Implementation Reference

• src/clickup_mcp/tools.py:1022-1050 (handler)

  The core handler function that loops over task_ids, resolves each to internal ID using _resolve_task_id helper, constructs UpdateTaskRequest from updates dict, and calls client.update_task for each.
  async def bulk_update_tasks( self, task_ids: List[str], updates: Dict[str, Any] ) -> Dict[str, Any]: """Update multiple tasks at once.""" results = {"updated": [], "failed": []} # Convert updates dict to UpdateTaskRequest format update_request = UpdateTaskRequest() if "status" in updates: update_request.status = updates["status"] if "priority" in updates: update_request.priority = updates["priority"] if "assignees_add" in updates: update_request.assignees = {"add": updates["assignees_add"]} if "assignees_remove" in updates: if update_request.assignees is None: update_request.assignees = {} update_request.assignees["rem"] = updates["assignees_remove"] 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) await self.client.update_task(resolved_task.id, update_request) results["updated"].append(task_id) except Exception as e: results["failed"].append({"task_id": task_id, "error": str(e)}) return results
• src/clickup_mcp/tools.py:332-350 (schema)

  The MCP Tool schema definition including name, description, and inputSchema for validating bulk_update_tasks inputs.
  Tool( name="bulk_update_tasks", description="Update multiple tasks at once", inputSchema={ "type": "object", "properties": { "task_ids": { "type": "array", "items": {"type": "string"}, "description": "List of task IDs to update", }, "updates": { "type": "object", "description": "Updates to apply (status, priority, assignees, etc.)", }, }, "required": ["task_ids", "updates"], }, ),
• src/clickup_mcp/tools.py:23-57 (registration)

  Registration of the bulk_update_tasks method in the ClickUpTools._tools dictionary, mapping tool name to handler function. Used by call_tool.
  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/tools.py:527-567 (helper)

  Helper method _resolve_task_id used by bulk_update_tasks (and others) to resolve flexible task_id formats to internal ClickUp task IDs.
  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
• src/clickup_mcp/server.py:41-44 (registration)

  MCP server registration: list_tools handler that returns all tool definitions including bulk_update_tasks schema.
  @self.server.list_tools() async def list_tools() -> List[Tool]: """List all available tools.""" return self.tools.get_tool_definitions()