ClickUp MCP Server

Instructions

Implementation Reference

• src/clickup_mcp/tools.py:1005-1018 (handler)

  The primary handler function for the MCP tool 'find_list_by_name'. It calls the ClickUpClient's find_list_by_name method and formats the result into a dictionary response.

  async def find_list_by_name(self, name: str, space_id: Optional[str] = None) -> Dict[str, Any]:
      """Find list by name."""
      lst = await self.client.find_list_by_name(name, space_id)
  
      if not lst:
          return {"error": f"List '{name}' not found"}
  
      return {
          "id": lst.id,
          "name": lst.name,
          "space": lst.space.get("name", "Unknown"),
          "folder": lst.folder.get("name") if lst.folder else None,
          "found": True,
      }

• src/clickup_mcp/tools.py:319-330 (schema)

  The input schema definition for the 'find_list_by_name' tool, specifying parameters 'name' (required) and optional 'space_id'.

  Tool(
      name="find_list_by_name",
      description="Find a list by name",
      inputSchema={
          "type": "object",
          "properties": {
              "name": {"type": "string", "description": "List name to search for"},
              "space_id": {"type": "string", "description": "Space ID to search in"},
          },
          "required": ["name"],
      },
  ),

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

  Registration of the 'find_list_by_name' handler in the _tools dictionary within ClickUpTools class, mapping tool name to its implementation method.

  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/client.py:240-270 (helper)

  Supporting helper method in ClickUpClient that performs the actual search for a list by name across space lists and subfolders, used by the tool handler.

  async def find_list_by_name(
      self,
      name: str,
      space_id: Optional[str] = None,
  ) -> Optional[ClickUpList]:
      """Find a list by name in a space."""
      if not space_id:
          # Search in all spaces if not specified
          spaces = await self.get_spaces()
          for space in spaces:
              result = await self.find_list_by_name(name, space.id)
              if result:
                  return result
          return None
  
      # Get all lists in the space
      lists = await self.get_lists(space_id=space_id)
  
      # Also check folders
      folders = await self.get_folders(space_id)
      for folder in folders:
          folder_lists = await self.get_lists(folder_id=folder.id)
          lists.extend(folder_lists)
  
      # Find by name (case-insensitive)
      name_lower = name.lower()
      for lst in lists:
          if lst.name.lower() == name_lower:
              return lst
  
      return None